Schema Compiler

JSON Schema has evolved through five major dialects over a decade, each with different keywords, reference semantics, and edge cases. OpenAPI adds its own variations. We built a schema compiler that handles all of them.

Multi-Dialect Parsing

The compiler handles five schema dialects transparently: JSON Schema Draft 2020-12, Draft 07, Draft 05, OpenAPI 3.1, and OpenAPI 3.0. Each has its own keyword semantics and reference resolution rules. Schemas written in any dialect work correctly without manual conversion.

Vocabulary Modularity

Draft 2020-12 organizes keywords into vocabularies: Core, Applicator, Validation, Unevaluated, Format, Content, and Metadata. Dialects compose vocabularies rather than duplicating keywords. Draft 05 and Draft 07 share the same Core and Validation keywords because the semantics haven’t changed—only the combinations differ.

OpenAPI 3.0 reuses Draft 05’s vocabularies but adds nullable with distinct semantics (a modifier on type, not an additional type value). OpenAPI 3.1 shifts to Draft 2020-12’s vocabularies. The same $ref implementation works across all five dialects because vocabularies are the unit of reuse.

Keyword-Centric Architecture

Each keyword—type, properties, allOf, etc.—is a first-class behavior unit controlling its own parsing, validation, traversal, and transformation. Traditional implementations split these concerns across multiple systems. Adding a keyword means modifying each system. This architecture inverts that: add a custom keyword and it automatically participates in validation and tree-shaking without touching core logic.

Keywords declare dependencies on other keywords, enabling correct evaluation order through topological sort. Virtual keywords create logical barriers without requiring physical presence.

$ref and $dynamicRef

JSON References resolve automatically during parsing, handling both local and remote references. Draft 2020-12’s $dynamicRef and $dynamicAnchor enable truly recursive schema definitions that weren’t possible with static references.

The recursive schema problem: with static $ref, you can’t write a schema for “a tree where nodes can be any type including tree.” Dynamic references resolve at runtime against the outermost dynamic anchor in the current scope, enabling polymorphic recursion where constraints propagate through the entire structure.

Format Validators

Complete suite: date-time, date, time, duration; email and idn-email; hostname and idn-hostname; ipv4 and ipv6; uri, uri-reference, iri, iri-reference; uri-template; json-pointer and relative-json-pointer; regex. Three modes: skip, validate known, or strict.

OpenAPI 3.0 Nullable

OpenAPI 3.0’s nullable: true has fundamentally different semantics from JSON Schema constraint intersections. The type keyword must be a string, not an array. Validation passes for null when both type is defined and nullable is true. Normalization happens once at parse time.