Skip to main content
JSON Schema builders and validation without 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.
Atomic validates tool arguments with it; see Tool parameter schemas. Extensions can import it from the host without installing it.

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.
A recursive schema needs its type spelled out, since TypeScript cannot infer one from the builders. Its 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:
TypeBox’s 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:
  1. Optional nulls. A null in an optional property whose schema rejects null is dropped, as if omitted.
  2. Conversions, ported from TypeBox 1.3.27’s Value.Convert and keyed on JSON Schema keywords (the first that applies to a schema): $ref follows the reference; const and enum take the member the value converts to; anyOf/oneOf keep a value one branch accepts, else take the first branch’s conversion the whole schema accepts; allOf converts with each member in turn; then by type:
    • string: numbers and booleans to their text, null to "null".
    • number: numeric strings ("" is 0), "true"/"false", booleans to 1/0, null to 0.
    • integer: as number, then truncated ("3.5" and 3.5 become 3).
    • boolean: "true"/"false" (any case), "1"/"0", 1/0, null to false.
    • null: "null", "undefined", "", "0", 0 and false.
    • bigint: integer strings ("12", "12n"; "12.9" truncated), numbers truncated, "true"/"false" and booleans to 1n/0n, null to 0n.
    • undefined: "undefined", "null", "", "0", 0, 0n, false and null.
    • array: a single value becomes a one-item array, then each item converts; a tuple (prefixItems or an items array) converts its items and never wraps.
    • object: each property converts by properties, patternProperties or additionalProperties.
  3. 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, null from "", 0 and false, and null to "", 0 or false. A value that already has one of a type array’s types stays.
Where passes 2 and 3 disagree, pass 2 wins: 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 undefined counts as absent, as in TypeBox. A required property set to undefined is present: valid when its schema takes undefined (Type.Undefined() in it, Type.Unknown(), Type.Any()), else missing.
  • { type: "bytes", minLength, maxLength } matches a Uint8Array of that length, an extension for values that never pass through JSON.
  • { type: "bigint" } (TypeBox’s Type.BigInt) matches a bigint. 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’s Type.Undefined) matches undefined.
  • equal(a, b) is JSON equality as const, enum and uniqueItems compare (TypeBox’s Value.Equal).

Supported keywords

  • Every validation keyword of drafts 2020-12 and 7, including draft 7’s dependencies and items arrays with additionalItems.
  • $id, $anchor, $ref (local, by anchor, relative and remote), $dynamicRef and $dynamicAnchor.
  • unevaluatedProperties and unevaluatedItems.
  • pattern and patternProperties are ECMAScript regular expressions with the u flag.
  • Not supported: meta-schemas that switch vocabularies on or off ($vocabulary), contentMediaType and contentEncoding assertions (optional in the spec), and draft 2019-09’s $recursiveRef.