xschema

Adapters convert JSON Schema to native validation code. This guide covers the core concepts for building adapters in any language.

Overview

Adapters are simple by design. The Go CLI handles all the hard work:

CLI handles	Adapter handles
Config discovery	Parse IR to code
Schema fetching	Render validation library syntax
`$ref` resolution	Generate import statements
Draft normalization	Return type expressions
Bundling `$defs`
Validation against meta-schema

Your adapter receives pre-bundled, normalized, validated schemas via stdin and outputs generated code via stdout.

Adapter Protocol

Adapters communicate with the Go CLI via stdin/stdout JSON. The CLI sends pre-bundled schemas; adapters return generated code.

See the Adapter Protocol reference for the complete specification.

Intermediate Representation (IR)

All adapters parse JSON Schema into a common Intermediate Representation - a discriminated union that's easy to pattern match against. This IR is:

Exhaustively matchable via the kind discriminator
Renderer-friendly - contains all info needed for code generation
Pre-processed - no $ref resolution needed, drafts normalized

Each language provides its own IR implementation. See the language-specific guides below for details on node kinds and constraint types.

Important Notes

Schemas are Pre-Bundled

The Go CLI resolves all $ref and embeds definitions in $defs. Your adapter will never see unresolved references.

Drafts are Normalized

All schemas are normalized to draft2020-12 syntax. You don't need to handle:

definitions (converted to $defs)
items as array (converted to prefixItems)
additionalItems (converted to items)
Boolean exclusiveMinimum/exclusiveMaximum (converted to numeric)

Forbidden Keywords

The CLI blocks schemas using dynamic features that can't be statically compiled:

$dynamicRef / $dynamicAnchor
$recursiveRef / $recursiveAnchor

Testing with Compliance Suite

After building your adapter, test it against the official JSON Schema Test Suite:

# Run compliance tests for your adapter
xschema compliance --adapter-path ./path/to/your-adapter

# Test a specific draft
xschema compliance --adapter-path ./path/to/your-adapter --draft draft2020-12

# Test specific keywords during development
xschema compliance --adapter-path ./path/to/your-adapter --keyword properties --keyword required

# Generate full compliance report
xschema compliance --adapter-path ./path/to/your-adapter --dev-report

Understanding Coverage

Coverage is calculated as:

Coverage = Passed / (Total - Unsupported) * 100

"Unsupported" tests involve features that cannot be statically compiled (e.g., $dynamicRef). These are excluded from the denominator, so 100% coverage means "handles everything that can be handled."

See Unsupported Features for the complete list.

Language Guides

TypeScript

Build adapters using @xschemadev/core

Building Adapters