Skip to content

schema.md

Latest commit

 

History

History
39 lines (32 loc) · 2.24 KB

schema.md

File metadata and controls

39 lines (32 loc) · 2.24 KB
Raw

Schema language

Every declaration has two inseparable surfaces:

  • safeParse(value) returns typed data or immutable, path-addressable issues.
  • jsonSchema is a deeply frozen, deterministically ordered JSON Schema object.

Built-ins include strings and common formats, finite numbers and integers, booleans, null, strict objects, arrays, records, enums, literals, optional and nullable values, and oneOf / anyOf / allOf composition.

optional(nullable(value)) and nullable(optional(value)) both produce an optional object property that accepts null; modifier order does not discard optionality. allOf composes the recognized keys of strict object members and rejects keys recognized by none of them. Its draft 2020-12 projection uses unevaluatedProperties: false so standards-compliant validators enforce the same contract as safeParse(). When multiple members produce the same parsed key, deeply equal values compose normally; differing values fail with a conflicting_value issue at that key instead of being silently overwritten.

Constraints written into a built-in schema are executable. This includes string length, pattern and supported formats; numeric bounds and multiples; array size and uniqueness; and object size and additional-property schemas. Strict objects keep the generic Unknown key. issue for unrelated keys. A single insertion, deletion, substitution, or adjacent transposition from a declared key adds a deterministic Did you mean "key"? suggestion.

schema.raw(projection, safeParse) supports specialized formats while keeping the executable-schema invariant. The callback must return a SafeParseResult. There is intentionally no projection-only reference declaration.

Recursive declarations are not supported by the eager object(), array(), record, wrapper, or combinator builders. An incomplete child schema throws a purpose-built error with this guidance instead of an internal property-access error. Use schema.raw(projection, safeParse) when manual recursive validation is required. raw() does not discover recursion or synthesize $ref entries: its jsonSchema is exactly the explicit projection supplied by the caller, so a flat placeholder projection remains flat and does not describe the recursive runtime structure.