Introducing a new way to review your PRs.

Read the announcement

earendil-works / pi

AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI

View on GitHub

13 documents · Updated Nov 19, 2026

docs / schema

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

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 $id indexing or baseFor() changes, local refs under relative root ids can resolve to the wrong document, causing check(), errors(), and parse() 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 plain typeof v === "number" or skip Number.isFinite, schemas can accept NaN/Infinity values that JSON Schema and TypeBox-style schemas should reject.
  • packages/…/explain.ts explicitly notes that $dynamicRef errors 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.