Skip to content
RANDSUMgames

The Schema API

@randsum/games/schema is the toolkit behind the game subpaths. It validates a .randsum.json spec, resolves its external references, and generates the TypeScript module for it. Use it to check a spec you are writing, or to build your own game modules from specs.

validateSpec checks any value against the .randsum.json JSON Schema and returns a structured result instead of throwing:

import { validateSpec } from '@randsum/games/schema'
const result = validateSpec(unknownData)
if (!result.valid) {
for (const error of result.errors) {
console.error(error.path, error.message)
}
} else {
console.log('Spec is valid')
}

The result is { valid: true } or { valid: false, errors }, where each error has a JSON path and a message.

generateCode turns a spec into the source of a game module: its input types, roll() function, result type and error handling. It returns a Promise<string>.

import { generateCode, validateSpec } from '@randsum/games/schema'
const spec = {
$schema: 'https://randsum.dev/schemas/v1/randsum.json',
name: 'Simple d20',
shortcode: 'simple',
game_url: 'https://example.com',
tables: {
outcome: {
ranges: [
{ min: 15, max: 20, result: 'success' },
{ min: 8, max: 14, result: 'partial' },
{ min: 1, max: 7, result: 'failure' }
]
}
},
roll: {
dice: { pool: { sides: 20 }, quantity: 1 },
resolve: 'sum',
outcome: { tableLookup: { $ref: '#/tables/outcome' } }
}
}
if (validateSpec(spec).valid) {
const source = await generateCode(spec)
// export type SimpleRollResult = 'failure' | 'partial' | 'success'
// export function roll(input?: Record<string, never>): GameRollResult<...>
}

The generated module imports roll from @randsum/roller/roll and its shared types and errors from the games package’s own ./types and ./lib/ files, so it is written to sit beside them in packages/games/src/. That is how every built-in game is made: bun run --filter @randsum/games gen writes each <game>.generated.ts.

A spec can point at data hosted elsewhere, as Salvage Union’s tables do. resolveExternalRefs fetches every external $ref URL and inlines the data, returning the resolved spec:

import { resolveExternalRefs, validateSpec } from '@randsum/games/schema'
const spec = JSON.parse(rawJson)
const resolved = await resolveExternalRefs(spec)
const result = validateSpec(resolved)

It throws a SchemaError with code 'EXTERNAL_REF_FAILED' when a reference cannot be fetched.

Looks a value up in a range-keyed table, the shape Salvage Union’s tables use:

import { lookupByRange } from '@randsum/games/schema'
const table = {
'15-20': { label: 'Success', value: 'success' },
'8-14': { label: 'Partial', value: 'partial' },
'1-7': { label: 'Failure', value: 'failure' }
}
const match = lookupByRange(table, 18)
console.log(match.key) // '15-20'
console.log(match.result.label) // 'Success'
  • specToFilename(name): the file name a game’s name maps to (e.g., 'Blades in the Dark' becomes 'blades-in-the-dark').
  • SchemaError: the error class the schema tools and the generated games throw. Its code is one of 'INVALID_SPEC', 'EXTERNAL_REF_FAILED', 'NO_TABLE_MATCH', 'REF_NOT_FOUND', 'INPUT_NOT_FOUND', 'INVALID_INPUT_TYPE' or 'CONDITION_TYPE_MISMATCH'.
  • Types: RandSumSpec and the spec-section types, ValidationResult, SpecValidationIssue, SchemaErrorCode and GenerateCodeOptions.