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.
Validate a spec
Section titled “Validate a spec”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.
Generate TypeScript
Section titled “Generate TypeScript”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.
Resolve external references
Section titled “Resolve external references”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.
lookupByRange
Section titled “lookupByRange”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'Other exports
Section titled “Other exports”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. Itscodeis one of'INVALID_SPEC','EXTERNAL_REF_FAILED','NO_TABLE_MATCH','REF_NOT_FOUND','INPUT_NOT_FOUND','INVALID_INPUT_TYPE'or'CONDITION_TYPE_MISMATCH'.- Types:
RandSumSpecand the spec-section types,ValidationResult,SpecValidationIssue,SchemaErrorCodeandGenerateCodeOptions.
Learn more
Section titled “Learn more”- Schema Overview: how
.randsum.jsonspecs work - Schema Reference: field-by-field spec documentation
- Contributing a Game: add a new game to the generated subpaths