eval. A schema compiles once into plain closures, so it checks values
at close to the speed of validators that generate code, also under a strict Content Security Policy, and needs no
dependencies.
- Drafts 2020-12 and 7. Passes 2,222 of the 2,223 core tests of the official JSON-Schema-Test-Suite.
- Builders return plain JSON Schema typed with the values it accepts; a compiled check narrows to that type.
- Errors as JSON Pointer paths. A missing or unknown field is reported at the field.
- Never modifies a schema; frozen schemas work.
- 8.5 KB minified and gzipped. Format checks are an optional import.
Installation
Usage
Read is plain JSON Schema ({ type: "object", properties: {...}, required: ["path", "mode"], additionalProperties: false }), ready for a tool definition or JSON.stringify. compile takes any JSON Schema, built with the builders
or not.
check(value) is the fast path: a boolean, no allocations for most schemas, and a plain function you can pass
around. errors(value) explains a failure and returns [] for a valid value. It is built on the first failure and
kept, so a schema whose values always pass never pays for it. validate(value) combines the two without changing
the value: { ok: true, value } or { ok: false, errors }.
Builders
Every builder also takes
title, description, examples, deprecated and default. A default is an annotation;
validation never inserts it.
A union of objects tagged by a lit() property checks and reports by the tag: only the branch the tag selects runs.
id must be
unique among the recursive schemas within one schema:
Static also types schemas built with TypeBox 1.x, read from TypeBox’s type shapes (@bastani/atomic-schema does not import
TypeBox): String, Number, Integer, Boolean, Null, Literal, Array, Object (with Type.Optional and
Type.Readonly properties), Union, Record, Enum, Tuple, BigInt, Undefined, Unsafe, Unknown and Any
give TypeBox’s own static type, so Static<typeof Type.Object({ path: Type.String() })> is { path: string }. Other
TypeBox kinds (Intersect, Cyclic, Ref, …) give unknown where they stand. Other JSON Schema objects give
unknown.
Options
formats has every format 2020-12 defines (date-time, email, uri, uuid, ipv6, …), plus url and
json-pointer-uri-fragment, which TypeBox and ajv-formats also check. Pass your own map to check fewer formats, or
custom ones.
A $ref that names nothing (a missing definition, a document not in schemas) throws when the schema compiles. With
unresolvedRefs: "reject" it compiles as false instead: only values at that place fail, with the error
unresolved reference <ref>, and the rest of the schema works. Use it for schemas from other systems, such as MCP
servers, whose references may dangle.
TypeBox schemas
TypeBox 1.x schemas are JSON Schema, so they compile as they are:BigInt and Undefined are supported (see Values). Its other JavaScript-only types (Function, Symbol,
…), refinements and codecs are not JSON Schema and are not supported.
Coercion
compile(schema, { coerce: true }) adds coerce() and parse(), for loosely typed input such as a model’s tool call
arguments. Without the option the validator has neither, and its check pays nothing for them: the coercion rules are
built on the first coerce() or parse().
coerce(value) returns the coerced value. It copies only the paths it changes, returns value itself when nothing
changes, and never modifies value. A value no rule applies to stays as it is. parse(value) coerces, then checks:
{ ok: true, value } with the coerced value, or { ok: false, errors } with the errors of the coerced value.
Three passes run in order:
- Optional nulls. A
nullin an optional property whose schema rejectsnullis dropped, as if omitted. - Conversions, ported from TypeBox 1.3.27’s
Value.Convertand keyed on JSON Schema keywords (the first that applies to a schema):$reffollows the reference;constandenumtake the member the value converts to;anyOf/oneOfkeep a value one branch accepts, else take the first branch’s conversion the whole schema accepts;allOfconverts with each member in turn; then bytype:string: numbers and booleans to their text,nullto"null".number: numeric strings (""is 0),"true"/"false", booleans to 1/0,nullto 0.integer: asnumber, then truncated ("3.5"and3.5become 3).boolean:"true"/"false"(any case),"1"/"0", 1/0,nulltofalse.null:"null","undefined","","0", 0 andfalse.bigint: integer strings ("12","12n";"12.9"truncated), numbers truncated,"true"/"false"and booleans to 1n/0n,nullto 0n.undefined:"undefined","null","","0", 0, 0n,falseandnull.array: a single value becomes a one-item array, then each item converts; a tuple (prefixItemsor anitemsarray) converts its items and never wraps.object: each property converts byproperties,patternPropertiesoradditionalProperties.
- Primitive coercion by type, as Ajv’s
coerceTypes, for what pass 2 leaves (type arrays such as["integer", "null"]): numbers from numeric strings and booleans, booleans from"true"/"false"and 1/0, strings from numbers and booleans,nullfrom"", 0 andfalse, andnullto"", 0 orfalse. A value that already has one of a type array’s types stays.
null for a required string becomes "null", not "". A union’s
branches convert in order and only until one is accepted; a union node that also declares properties converts them into
each branch’s candidate before checking it. A recursive schema (a tree through $ref) that meets a value it cannot
convert leaves the value as it is, so check reports it, and results through a $ref are reused within one call, so a
recursive union does not convert (or explain) the same child once per branch.
Pass 1 drops optional nulls inside the values of properties, patternProperties and additionalProperties alike; a
pattern or additional key itself is never dropped. Items past a draft-7 items array (additionalItems) are not
coerced by any pass.
Values
- An optional property whose value is
undefinedcounts as absent, as in TypeBox. A required property set toundefinedis present: valid when its schema takesundefined(Type.Undefined()in it,Type.Unknown(),Type.Any()), else missing. { type: "bytes", minLength, maxLength }matches aUint8Arrayof that length, an extension for values that never pass through JSON.{ type: "bigint" }(TypeBox’sType.BigInt) matches abigint. The number keywords (minimum,maximum,exclusiveMinimum,exclusiveMaximum,multipleOf) apply to numbers and bigints alike, with bounds of either kind, as in TypeBox.{ type: "undefined" }(TypeBox’sType.Undefined) matchesundefined.equal(a, b)is JSON equality asconst,enumanduniqueItemscompare (TypeBox’sValue.Equal).
Supported keywords
- Every validation keyword of drafts 2020-12 and 7, including draft 7’s
dependenciesanditemsarrays withadditionalItems. $id,$anchor,$ref(local, by anchor, relative and remote),$dynamicRefand$dynamicAnchor.unevaluatedPropertiesandunevaluatedItems.patternandpatternPropertiesare ECMAScript regular expressions with theuflag.- Not supported: meta-schemas that switch vocabularies on or off (
$vocabulary),contentMediaTypeandcontentEncodingassertions (optional in the spec), and draft 2019-09’s$recursiveRef.