jsonschema-specifications

jsonschema-specifications packages the JSON Schema project’s own specification files — the meta-schemas and vocabulary definitions for every published draft, from Draft 3 through Draft 2020-12 — as installable Python package data. Rather than asking every JSON Schema library, linter, or code generator to vendor its own copy of these files and risk drifting out of sync with the spec, this package exposes them at runtime through a single object: REGISTRY, a referencing.jsonschema.SchemaRegistry pre-loaded and crawled so every meta-schema and vocabulary resolves by its canonical $id.

It is maintained by Julian Berman, the author of the jsonschema and referencing libraries, and is a direct dependency of the mainstream jsonschema validator itself — most Python developers pull it in transitively without ever importing it directly. Releases track JSON Schema specification updates rather than feature work, giving downstream tooling a clean way to pick up new draft support independent of the validator’s own release cadence.

What You Get

• A pre-built REGISTRY object containing every official JSON Schema meta-schema and vocabulary, already crawled and ready to resolve by $id
• Complete draft coverage from Draft 3 through Draft 2020-12, including the per-vocabulary files introduced in 2019-09 and 2020-12
• A referencing-native integration, so the registry composes directly with any referencing.Registry your own schemas or tooling already use
• Version releases that track JSON Schema specification updates, giving you an explicit, auditable way to pick up new draft support

Common Use Cases

• Building a custom JSON Schema validator or linter that needs the official meta-schemas without hand-copying spec files
• Resolving $refs against the canonical draft dialects when authoring or testing your own JSON Schemas
• Writing JSON Schema tooling (code generators, IDE plugins, documentation generators) that must recognize which draft a schema targets
• Depending on it transitively via jsonschema or another referencing-based validation library

Under The Hood

Architecture The package’s entire surface is two small modules. _core.py defines _schemas(), a generator that walks the bundled schemas/<draft>/ resource tree via importlib.resources.files() — handling both flat per-draft files and the nested per-vocabulary layout used by drafts 2019-09 and 2020-12 — parses each JSON file, and yields it as a referencing.Resource. __init__.py pipes that generator through the @ operator into referencing’s EMPTY_REGISTRY and calls .crawl() once at import time, producing the module-level REGISTRY singleton that is the package’s only public export. There is no runtime configuration, no classes, and no I/O beyond reading packaged resource files — it is a static-data package with a single computed artifact.

Tech Stack Pure Python 3.10-3.14 (plus PyPy), built with hatchling and versioned via hatch-vcs from git tags. The sole runtime dependency is referencing>=0.31.0, the schema-registry primitive shared across the wider jsonschema ecosystem. Schema data ships as package resources under jsonschema_specifications/schemas/. Development tooling includes ruff with an exhaustive, individually-justified select = ["ALL"] lint configuration, doc8 for the Sphinx docs, nox as the task runner, and coverage.py enforced at 100% via fail_under.

Code Quality The test suite is small but pointed: it asserts the registry actually resolves known meta-schema URIs to the expected content, that .crawl() is idempotent, and exercises a real filesystem edge case where stray .DS_Store files must be skipped during resource iteration. Coverage is enforced at 100% and CI runs on every push. Type annotations are deliberately not enforced in-repo (the ruff config notes “just let the type checker do this”), but the code carries explicit # type: ignore comments where needed. Given the tiny surface area there is little branching logic to speak of — the core function is a straightforward generator.

What Makes It Unique The notable design decision is what this package does not do: it implements no schema-crawling or $ref-resolution logic itself, delegating that entirely to referencing (maintained by the same author). Its sole job is to be the canonical, versioned, install-once source of the official JSON Schema Specification files, so downstream projects stop vendoring and copy-pasting meta-schemas that silently drift out of sync. Because releases track spec revisions rather than feature work, consumers get an explicit, auditable signal of exactly which draft support they’re running — decoupling “is my validator spec-current” from the validator library’s own release cadence.