Open-source project
json-schema-org/json-schema-spec avatar
json-schema-org/json-schema-spec

json-schema-spec: the repository where the JSON Schema drafts are written

The JSON Schema specification

5,223 stars480 forksJavaScriptNOASSERTION

At a glance

What is it?
This is not a validator. It is the Markdown source of the JSON Schema IETF Internet-Drafts, plus the Remark build that turns it into HTML and the meta-schema tests that keep it honest.
Who is it for?
Adopt this repository if you are writing, reviewing or implementing a JSON Schema draft and need the current source text, the section anchors and the meta-schema tests in one place. Do not clone it expecting a validator: it produces HTML and IETF XML, not validation results, and the README points to the separate JSON-Schema-Test-Suite repository for conformance tests.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • json-schema-org/json-schema-spec5,223 ★ · +59
Star history
Repository2026-09-232026-11-15
json-schema-org/json-schema-spec5.2k5.2k

59 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What json-schema-spec actually contains, and what it is not

The README opens with a line that describes the vocabulary, not the repository: JSON Schema is a vocabulary that allows you to validate, annotate, and manipulate JSON documents. The repository itself is described two paragraphs later, and the wording matters. This repository contains the sources for the work in progress of the next set of JSON Schema IETF Internet Draft (I-D) documents. For the latest released I-Ds, the README sends you to the Specification page on json-schema.org.

That distinction decides whether you should clone this at all. If you want to validate a payload against a schema, this is the wrong repository. If you are implementing a draft, reviewing a proposal, or trying to settle an argument about what the text says, it is the right one. The audience is spec editors, implementers of validators and code generators, and the people who file issues against behaviour that the prose does not pin down.

The repository is not archived. The last push was on 2026-10-31. The README carries a repostatus badge declaring the project active and in a stable, usable state.

How the Markdown becomes HTML: Remark, plugins and section anchors

The build is a Remark pipeline. The README states that the spec is built using Remark, a markdown engine with good support for plugins, and that a language server and a VSCode extension exist for linting and link checking while you write. The build script in package.json confirms the shape: it runs the remark CLI with a separate rc file, specs/.remarkrc-build.js, ignores everything except the specs directory and README.md, and writes output into web/.

The plugin list is where the editorial machinery lives. remark-validate-links checks for broken links across the documents. remark-gfm adds GitHub Flavored Markdown features such as footnotes and tables. remark-heading-id adds support for {#my-anchor} syntax so a heading can be referenced by URI fragment. A local plugin, remark/remark-headings.js, adds hierarchical section numbers to headings, and the README notes that a %appendix% prefix on a heading numbers it as an appendix instead. It also generates id anchors of the form #section-2-13 and #appendix-a, and turns each heading into a link to its own anchor.

A second local plugin, remark-reference-links, adds a shorthand for cross-references. The README gives this example: a heading defined as ## Foo {#foo} can be referenced elsewhere as {{foo}}, which renders as a link whose text is the section number, using Section or Appendix as appropriate. For a document that is read as a numbered specification, that is the difference between a link that survives renumbering and one that silently points at the wrong clause.

Code blocks get their own treatment. remark-code-titles adds titles to fenced blocks, and the languages jsonschema and json have special styling. The README warns that the title is parsed as a JSON string, so escaped characters need double escaping to survive. rehype-highlight handles syntax highlighting and rehype-highlight-code-lines adds line numbers, with support for ranges. remark-flexible-containers provides callout boxes of type warning, note, or experimental.

Building the spec locally and producing IETF drafts

The README gives the build command directly. To build all the spec files to HTML from the Markdown sources, run the following. The HTML files land in the web folder.

bash
npm run build -- specs

Individual files build the same way, and wildcards are supported, so you can rebuild only the core document while you edit it.

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

Linting runs through eslint and the remark CLI together. The remark invocation uses --frail, which means warnings are treated as failures, so a style slip stops the run rather than scrolling past.

bash
npm run lint

The Internet-Draft path is separate and containerised. npm run build-ietf is defined as docker-compose run --rm build. The compose file mounts the repository into /app in the container. The Dockerfile starts from fedora, installs Ruby and python3-pip, symlinks the Fedora CA bundle to /etc/pki/tls/cert.pem because kramdown-rfc aborts early if that default path is missing, then installs the kramdown-rfc gem and xml2rfc via pip. Its CMD converts each ietf/*.md file to XML with kramdown-rfc and then each XML file to HTML with xml2rfc, writing into web.

bash
npm run build-ietf

Expect the first run to be slow: it pulls a Fedora base image and installs Ruby gems and Python packages inside it. The repository also ships a .dockerignore, so the build context is not the whole working tree.

The meta-schema tests, and where conformance testing lives

The README is explicit that conformance tests for JSON Schema and its vocabularies may be found in their own repository, JSON-Schema-Test-Suite. What stays here is narrower: tests for the meta-schema. Those run with npm test, which package.json maps to vitest run --config=vitest-schema.config.js.

bash
npm test
npm run test:coverage

The coverage variant passes --coverage through to the same command and, according to the README, produces a detailed HTML report in the coverage directory alongside the CLI output. The coverage tooling is @hyperjump/json-schema-coverage, a devDependency.

This split is the single most misunderstood thing about the repository. If you are choosing a validator for production and you want to know how well it conforms, the test suite repository is the place to look, not this one. If you are changing the meta-schema itself, this is where the test that catches your mistake lives.

Limitations: a work-in-progress source tree with no release artefacts

The first limitation is stated by the project itself. The README calls this the work in progress of the next set of Internet-Drafts. Nothing here is a published standard, and the README directs readers to the website for the latest released I-Ds. If your implementation targets a stable draft, cloning main gives you text that may not match what you are implementing against.

The second is that the repository has no published releases. There is no versioned artefact to pin, no changelog in the repository, and no tagged draft to diff against. Your only reference points are the commit history and the Specification page. That makes this a poor dependency for anything automated: you cannot express the spec text you built against as a version range.

The third is the toolchain weight on the IETF path. Building drafts requires Docker, a Fedora base image, Ruby with the kramdown-rfc gem, and Python with xml2rfc. The Dockerfile even patches a CA bundle path because kramdown-rfc fails without it. That is a reasonable amount of machinery for a specification repository, but it is not a build you casually run on a laptop that has only Node installed.

Finally, the licence signal is inconsistent. package.json says MIT. The repository metadata reports NOASSERTION. The LICENSE file exists at the root. Read that file rather than trusting either the package field or the metadata badge.

Alternatives, and why you might not need this repository at all

For most engineers, the practical alternative is the published specification on json-schema.org plus a validator library in their own language. That route gives you a stable, released document and a runtime that answers yes or no about a payload. This repository gives you neither: it gives you the draft text, its build pipeline, and the meta-schema tests. The difference is between consuming a specification and editing one.

A second alternative is the JSON-Schema-Test-Suite repository, which the README names as the home of conformance tests for JSON Schema and its vocabularies. If your question is whether a given validator handles a keyword correctly, that repository answers it. This one will not, because its tests target the meta-schema rather than validator behaviour.

A third option is to read the drafts as plain Markdown on GitHub without building anything. The plugin layer exists to make the rendered HTML navigable: numbered sections, stable anchors, cross-references that resolve to section numbers, and line-numbered code blocks. If you only need to read the prose once, the raw files are enough and you can skip npm entirely. The build earns its keep when you are editing, because remark-validate-links and the --frail lint run catch broken references before a reviewer does.

Maintenance, contribution cost and licence implications

The last push was on 2026-10-31, and the repository is not archived. The README carries a repostatus badge describing the project as active and in a stable, usable state, and it opens a call for contributions and feedback, pointing at CONTRIBUTING.md for guidelines. Issue and pull request status is tracked through GitHub labels: Status: Available, Status: In Progress, Status: Review Needed, and Priority labels from Critical down to Low. The README states those labels follow Sensible GitHub Labels, and the repository root also contains an adr directory and a PROCESS.md, which is where the decision-making process is documented.

The upgrade cost is mostly toolchain drift. The devDependencies are caret-ranged across Remark, rehype, ESLint and Vitest, so a fresh npm install can pull newer plugin versions than the last author used. Because the lint script runs remark with --frail, a stricter plugin release can turn a previously passing tree red. The IETF build is pinned differently: it installs kramdown-rfc and xml2rfc without versions at container build time, so the draft output depends on whatever those package managers serve that day.

On licensing, package.json declares MIT while the repository metadata reports NOASSERTION. That is a discrepancy to resolve by reading the LICENSE file before you reuse the text or the build scripts. Nothing here is legal advice, and specification text reuse can raise questions that a licence identifier alone does not settle.

Editorial conclusion

Adopt this repository if you are writing, reviewing or implementing a JSON Schema draft and need the current source text, the section anchors and the meta-schema tests in one place. Do not clone it expecting a validator: it produces HTML and IETF XML, not validation results, and the README points to the separate JSON-Schema-Test-Suite repository for conformance tests. Before you rely on it for implementation work, check the Specification page on json-schema.org for the latest released Internet-Drafts and confirm whether the draft text you need has changed since you last read it.

Frequently asked questions

What is a JSON Schema?

The README describes JSON Schema as a vocabulary that allows you to validate, annotate, and manipulate JSON documents. This repository holds the sources for the specification documents that define that vocabulary.

How do I build the json-schema-spec HTML output?

Run npm run build -- specs to build all spec files from the Markdown sources, or npm run build -- specs/jsonschema-core.md for a single file. The README states the HTML files will be available in the web folder.

What is the current version of the JSON Schema specification?

The README does not name a version. It says this repository contains the work in progress of the next set of IETF Internet-Drafts, and directs readers to the Specification page on json-schema.org for the latest released I-Ds.

How do I specify a schema in a JSON file?

The README does not give an authoring walkthrough. It describes JSON Schema as a vocabulary for validating, annotating and manipulating JSON documents, and this repository holds the specification text that defines how a schema is written.

Official sources

  1. Issues
  2. json-schema-org/json-schema-spec on GitHub
  3. Project website
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/json-schema-org-json-schema-spec.svg)](https://hysenlabs.com/projects/json-schema-org-json-schema-spec)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/json-schema-org-json-schema-spec.svg)](https://hysenlabs.com/projects/json-schema-org-json-schema-spec)

Was this useful?