Schema package
Overview
Path-routing coverage: this doc owns packages/schema/**, including the public package entry points, validator/compiler internals, optional format bundle, vendored conformance fixtures, and package-local tests.
packages/schema publishes @earendil-works/pi-schema, a JSON Schema validation package whose main export is packages/…/index.ts. The package is intentionally CSP-friendly: compile() in packages/…/validator.ts builds closures rather than emitting or evaling code. It returns a Validator with a detachable check type guard, errors() for JSON-Pointer-addressed ValidationErrors, and validate() for a check-or-errors result. When callers pass { coerce: true }, compile() instead returns CoercingValidator, adding coerce() and parse().
The public type and option surface lives in packages/…/types.ts. CompileOptions selects draft "2020-12" by default or draft "7", optionally supplies named format checks, registers external schemas for $ref, enables coercion, and controls unresolved references. By default an unresolved $ref throws during compile; with unresolvedRefs: "reject", packages/…/resolver.ts resolves the missing target to false, so only values at that site fail and packages/…/explain.ts reports the keyword as $ref with an unresolved reference message.
The schema-builder API in packages/…/builders.ts creates plain JSON Schema objects while carrying a type-only brand for Static<typeof schema>. Builders cover primitives (str, num, int, bigint, bool, nul, bytes, unknown), literals/enums (lit, oneOf), arrays/tuples/maps, object schemas (obj, opt, Optional), unions/nullability, recursive schemas, and unsafe<T>() for externally checked shapes. obj() defaults to closed objects by emitting additionalProperties: false; open: true omits that restriction. recursive() assigns a $id and uses $ref to point at it. packages/…/typebox-static.ts extends Static to common TypeBox 1.x shapes by reading TypeBox's structural markers (~kind, ~optional, ~readonly, ~unsafe) without importing TypeBox at runtime.
packages/…/compiler.ts is the central compiler. It owns one compile's caches, Resolver, selected draft, format map, and dynamic-scope state. root() compiles the schema into one Check; check() caches by schema object and inserts an indirection before building a node so recursive references can close over themselves. The compiler groups assertions by value category: string constraints use shared regexes and optional formats, number/bigint constraints share bounds logic, object schemas can become specialized closed/open-object loops, arrays can become a single list loop for common prefix/rest-item cases, and in-place keywords handle enum, const, allOf, anyOf, oneOf, not, conditionals, $ref, and $dynamicRef. It has fast paths for annotation-only type schemas, primitive-const unions, nullable or bare-type unions, and tagged object unions where branches share a required const property.
Reference handling is isolated in packages/…/resolver.ts. The resolver lazily indexes the root schema and CompileOptions.schemas, tracking resources by document URI, $anchor/draft-7 fragment ids, $dynamicAnchors, and each schema object's effective base URI. It applies draft-specific $id and $ref semantics: draft 7 treats a schema object with $ref as ref-only and makes sibling keywords inert, while draft 2020-12 can combine $ref with sibling assertions. Compiler uses this resolver for normal references, dynamic references, annotating checks, errors, and coercion.
packages/…/annotations.ts exists for draft 2020-12 unevaluatedProperties and unevaluatedItems. A schema using either keyword compiles to annotating closures that record evaluated object keys, array prefixes, and indexes matched by contains; then unevaluated* checks only the parts no earlier keyword evaluated. This annotating path is separate from the common plain-check path so schemas without unevaluated* avoid the bookkeeping.
packages/…/checks.ts contains the reusable check factories and runtime semantics. Important non-standard extensions are deliberate: bytes validates Uint8Array, bigint validates JavaScript bigints with TypeBox-style bounds, and undefined is accepted as a TypeBox-compatible type. Numbers must be finite, integer implies Number.isInteger, JSON equality powers const/enum/uniqueItems, and object validation treats undefined optional properties as absent while still letting a required property's schema decide whether explicit undefined is valid.
Failure reporting in packages/…/explain.ts is a second walk over the schema, reached only after check() fails. It reuses compiler checks for subschemas, emits ValidationError objects with JSON Pointer paths, descends through refs, chooses clearer tagged-union errors when possible, and memoizes object/reference explanations during one call to avoid exponential recursion. Dynamic-reference errors are approximate because the explainer does not run inside the original dynamic scope.
Coercion in packages/…/coerce.ts is opt-in and lazy: CoercingValidator constructs a Coercer on first coerce() or parse(). Its three passes drop null from optional non-nullable properties, port TypeBox 1.3.27 Value.Convert rules over plain JSON Schema structure, then apply Ajv-like primitive coercion by type and type arrays. The implementation is copy-on-write, never mutates input or schemas, memoizes recursive ref conversions within one call, and leaves uncoercible values unchanged so normal validation reports them.
Formats are an optional secondary package export. packages/…/index.ts exports a frozen formats map for JSON Schema 2020-12 names plus url and json-pointer-uri-fragment; compile() only asserts format when this or another map is supplied. The individual checks under packages/schema/src/formats/typebox/** are adapted from TypeBox 1.3.27 and include embedded MIT license headers in the copied files.
The package-local tests cover both behavior and compatibility. packages/…/conformance.test.ts runs the vendored JSON-Schema-Test-Suite fixtures under packages/schema/test/fixtures/json-schema-test-suite/** for drafts 2020-12 and 7, with remote and meta-schema loading in packages/…/suite.ts and explicit known failures for unsupported vocabulary switching, cross-draft reference semantics, and content media validation. Focused tests cover validators and errors (packages/…/validator.test.ts), builders and static types (packages/…/builders.test.ts, packages/…/typebox-static.test.ts), coercion including a large TypeBox conversion port (packages/…/coerce.test.ts, packages/…/coerce-typebox.test.ts), shared regex lifetime (packages/…/shared.test.ts), and deep equality (packages/…/equal.test.ts).
Coupling
- If the package export surface changes, update both packages/…/index.ts and packages/…/package.json. The package currently publishes only
.and./formats; adding a new public module underpackages/schema/src/**is not reachable to consumers unlessexportsexposes it. - If
CompileOptionschanges in packages/…/types.ts, verify every consumer path that constructs compile-time helpers: packages/…/validator.ts passes options intoCompiler, packages/…/compiler.ts readsdraftandformats, packages/…/resolver.ts readsschemasandunresolvedRefs, and packages/…/coerce.ts receives the same compiler/options throughCoercingValidator. - If reference-base or
$idlogic changes in packages/…/resolver.ts, check all three call sites that depend on identical base computation: fast validation in packages/…/compiler.ts, error walking in packages/…/explain.ts, and coercion in packages/…/coerce.ts. The tests in packages/…/validator.test.ts include relative$idregressions across plain checks, unevaluated keywords, nested resources, errors, and coercion. - If a keyword is added to compilation in packages/…/compiler.ts, also decide whether it must be explained in packages/…/explain.ts, coerced through in packages/…/coerce.ts, indexed as a subschema in packages/…/resolver.ts, and included in annotation tracking in packages/…/annotations.ts. A keyword can otherwise validate but produce generic errors, skip refs under that keyword, or break
unevaluated*semantics. - If TypeBox is upgraded or TypeBox compatibility changes, verify three separate surfaces: TypeBox static typing in packages/…/typebox-static.ts, runtime extra types in packages/…/checks.ts and packages/…/compiler.ts (
bigint,bytes,undefined), and conversion parity in packages/…/coerce.ts. The pinned dev dependency is in packages/…/package.json, and parity tests live in packages/…/typebox-static.test.ts and packages/…/coerce-typebox.test.ts. - If a standard format implementation changes under
packages/schema/src/formats/typebox/**, update packages/…/index.ts if the public map changes and preserve the copied TypeBox license header where code remains adapted from TypeBox. Conformance format assertions in packages/…/conformance.test.ts only run withformatsfor optional format test files, matchingcompile()'s default annotation behavior. - If schema builders in packages/…/builders.ts change emitted JSON, verify both runtime validation and the type brand.
Staticis inferred from the builder brand first, then from TypeBox structural markers; an accidental runtime property for the brand or a change toOptionalshape can alterobj()output and TypeScript inference at once.
Risks
- packages/…/resolver.ts, packages/…/compiler.ts, packages/…/explain.ts, and packages/…/coerce.ts share fragile reference-base semantics. Recent history includes
2bd2c2d0a fix(schema): apply a relative root $id only once when resolving references (#11726), and packages/…/validator.test.ts carries regression tests for that bug class. If$idindexing orbaseFor()changes, local refs under relative root ids can resolve to the wrong document, causingcheck(),errors(), andparse()to disagree or throw. - Numeric validation is easy to drift from TypeBox/runtime expectations. Recent history includes
55a5c6914 fix(schema): num no longer takes nan and infinity, and the guard now lives in packages/…/checks.ts with tests in packages/…/validator.test.ts. If number checks use plaintypeof v === "number"or skipNumber.isFinite, schemas can acceptNaN/Infinityvalues that JSON Schema and TypeBox-style schemas should reject. - packages/…/explain.ts explicitly notes that
$dynamicReferrors are approximate because the error walk runs outside the original dynamic scope. If consumers start depending on exact diagnostics for schemas with$dynamicRef, validation may be correct while reported errors point at the fallback or generic dynamic-ref failure instead of the dynamically selected target.