json-schema-spec: Inside the JSON Schema Specification Source Repository

What JSON Schema Is and What This Repository Contains

JSON Schema is a vocabulary for validating, annotating, and manipulating JSON documents. A JSON Schema document describes the expected shape of JSON data: required properties, allowed types, minimum and maximum values, and other constraints. Validators apply a schema to a JSON document and report whether it conforms.

This repository contains the source files for the next version of the JSON Schema IETF Internet Draft specifications. The README describes the content as work in progress; the latest released drafts are published at json-schema.org/specification.html, not in this repository. The specs/ directory holds the actual specification text as Markdown files, which the build pipeline converts to HTML in the web/ directory. The ietf/ directory holds components maintained as IETF Internet-Draft documents.

The repository is distinct from the validator implementations, the test suite, and the website. The conformance test suite lives at github.com/json-schema-org/JSON-Schema-Test-Suite. The website source is in a separate repository at github.com/json-schema-org/website. This repository is strictly the specification text and its build toolchain.

Building the Specification from Source

The specification is authored in Markdown and built to HTML using a Remark pipeline. To build all spec files in the specs/ directory:

npm run build -- specs

To build a single file:

npm run build -- specs/jsonschema-core.md

Wildcards are supported:

npm run build -- specs/jsonschema-*.md

The HTML output goes to the web/ directory. The README suggests serving it with a local HTTP server for review.

To run the meta-schema tests:

npm test

For a test coverage report:

npm run test:coverage

The coverage directory receives a detailed HTML report in addition to the CLI output. The README suggests serving it with:

npx http-server coverage

Building the IETF Internet-Draft components requires Docker:

npm run build-ietf

The Dockerfile builds a Fedora image with Ruby and Python, installs kramdown-rfc and xml2rfc, and processes the .md files in the ietf/ directory into .xml and then into HTML.

How the Remark Build Pipeline Transforms Specification Markdown

The build pipeline uses Remark, a Markdown processing engine, with a collection of custom and third-party plugins. Each plugin adds a specific capability to the Markdown syntax used in the specification files.

remark-heading-id adds support for the `{#my-anchor}` syntax, which attaches an explicit HTML id to a heading. This lets authors write stable cross-references that do not change when section text is edited.

remark-headings, a custom plugin in the remark/ directory, automatically adds hierarchical section numbers to headings, generates anchors where none exist, and turns each heading into a self-linking element. Appendix headings are marked with a `%appendix%` prefix.

remark-reference-links, another custom plugin, introduces a `{{foo}}` syntax for referencing sections by their anchor. At build time, this resolves to a link with the section number as its text, such as "Section 2.3" or "Appendix A."

remark-code-titles, a third custom plugin, allows labeling code blocks with a JSON-encoded title string. The jsonschema and json languages get special styling.

remark-flexible-containers adds callout boxes for warning, note, and experimental content using a fenced-container syntax.

The linting rules come from remark-preset-lint-consistent, remark-preset-lint-markdown-style-guide, and remark-preset-lint-recommended. remark-validate-links checks for broken internal and external links. Running the full lint check:

npm run lint

The IETF Internet-Draft Track and What It Means

JSON Schema is developed as an IETF Internet-Draft, not as a W3C standard or an ISO specification. The IETF process does not require organizational membership. Internet-Drafts are working documents: they expire after six months unless updated, and they can be published as Informational RFCs or left as drafts if the working group does not pursue formal standardization.

The ietf/ directory holds the Markdown files for components being maintained as IETF Internet-Drafts. The build process converts these to xml2rfc XML format using kramdown-rfc, then to HTML using xml2rfc. The README links to xml2rfc, IETF TAO, and RFC 7322 as references for the authoring format and process.

The choice of IETF format constrains the specification structure. xml2rfc enforces document conventions around section numbering, references, and IANA considerations. The custom Remark plugins in the web build pipeline are partly designed to reproduce these conventions in the more human-readable HTML output.

For implementers who need to cite a specific version of the specification, the IETF draft designation (such as draft-bhutton-json-schema-01) is the stable identifier during active development. The json-schema.org specification page lists the latest published drafts.

Where the Repository Ends and Implementation Begins

The json-schema-spec repository does not contain a JSON Schema validator. It contains the specification that a validator should implement. An implementer reads the spec and writes code; the spec repository does not generate that code.

The test suite in json-schema-org/JSON-Schema-Test-Suite is the conformance test set. The README points to it explicitly for testing validator implementations. Meta-schema tests for the specification's own schema are included in this repository and run via `npm test`, but those tests verify the spec's own consistency, not third-party validator behavior.

The specification leaves several behaviors optional or implementation-defined. The handling of unknown keywords, the behavior of recursive schemas, and the interaction between vocabularies and dialect declarations are areas where the spec text has evolved across drafts. An implementer tracking the work-in-progress branch may encounter behavior that changes before the next published draft.

The ADR (Architectural Decision Record) directory documents design decisions the working group has already resolved. Filing an issue that revisits a closed ADR without new information is unlikely to change the outcome.

Comparing with OpenAPI Specification Authoring

The OpenAPI Specification, maintained by the OpenAPI Initiative, is a separate specification that uses JSON Schema as a component for describing request and response body schemas. OpenAPI adds an API description layer on top: paths, operations, authentication, and server definitions. The two projects share vocabulary but serve different purposes.

JSON Schema is a general-purpose schema language for any JSON document. OpenAPI's schema object is a constrained subset or dialect of JSON Schema, and different OpenAPI versions have tracked different JSON Schema drafts. An author contributing to json-schema-spec is working on the foundational vocabulary; an author contributing to the OpenAPI Specification is working on how that vocabulary is profiled for HTTP APIs.

For tooling authors, the difference matters: a JSON Schema validator must implement the full vocabulary, while an OpenAPI validator only needs the OpenAPI-profiled subset and may handle keywords differently.

Maintenance and Contribution Process

The last push to the repository was on 2026-09-04. The project uses Sensible GitHub Labels for issue tracking, with labels indicating status (Available, In Progress, Review Needed) and priority (Critical through Low). The README links to the current open issue listing filtered by each label.

The repository has no GitHub releases. Published drafts are submitted to the IETF and listed on the json-schema.org specification page, not through GitHub's release mechanism.

The package.json lists the license as MIT. The repository metadata reports NOASSERTION, which reflects that the specification text uses its own copyright terms rather than a standard open-source license. Contributors should read CONTRIBUTING.md for the specific terms before submitting pull requests.

The working group accepts financial contributions through Open Collective, linked from the README. The sponsors section lists current project sponsors.

Editorial conclusion

json-schema-spec is the correct repository for understanding what JSON Schema is specified to do, for filing issues against the vocabulary or meta-schema, and for building the next set of Internet Drafts from source. It is not a JSON Schema implementation library, a validator, or a conformance test suite: those are separate projects. Before contributing, read CONTRIBUTING.md for the labeling conventions and the ADR directory for architectural decisions the working group has already made. For released specification documents, the json-schema.org website is the stable reference.

Frequently asked questions

Official sources

1. Issues
2. json-schema-org/json-schema-spec on GitHub
3. Project website
4. README