JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.


  • Describes your existing data format(s).
  • Provides clear human- and machine- readable documentation.
  • Validates data which is useful for:
    • Automated testing.
    • Ensuring quality of client submitted data.

New to JSON Schema?

Learning a new specification can be daunting.

You should read our getting started guide!

You can also see our other learning resources.

Got questions?

The JSON Schema team and community are here to help!

At any point, feel free to join our Slack server.

We also monitor the jsonschema tag on StackOverflow.

Project Status

2021-02-01: Draft 2020-12 has been published!

The IETF document IDs are of the form draft-bhutton-*-00.

We are using dates for meta-schemas, which are what implementations should use to determine behavior, so we will usually refer to 2020-12 (without the word “draft”) on this web site.

See the Specification page for details about naming and numbering.

The Path to Standardization

The JSON Schema project intends to shepherd all three draft series to either: RFC status, the equivalent within another standards body, and/or join a foundation and establish self publication rules.

Read more

Currently, we are continuing to improve our self-published Internet-Drafts. We are not actively pursuing joining a standards organisation.

We have a few contacts related to each potential path, but if you have experience with such things and would like to help, please still contact us!

In the meantime, publication of Internet-Draft documents can be tracked through the IETF:

Internet-Drafts expire after six months, so our goal is to publish often enough to always have a set of unexpired drafts available. There may be brief gaps as we wrap up each draft and finalize the text.

The intention, particularly for vocabularies such as validation which have been widely implemented, is to remain as compatible as possible from draft to draft. However, these are still drafts, and given a clear enough need validated with the user community, major changes can occur.


The JSON document being validated or described we call the instance, and the document containing the description is called the schema.

The most basic schema is a blank JSON object, which constrains nothing, allows anything, and describes nothing:


You can apply constraints on an instance by adding validation keywords to the schema. For example, the “type” keyword can be used to restrict an instance to an object, array, string, number, boolean, or null:

{ "type": "string" }

JSON Schema is hypermedia ready, and ideal for annotating your existing JSON-based HTTP API. JSON Schema documents are identified by URIs, which can be used in HTTP Link headers, and inside JSON Schema documents to allow recursive definitions.

JSON Hyper-Schema

JSON Hyper-Schema is on hiatus / not currently maintained as of 2021.

This allows the team to focus the little time they do donate on JSON Schema core and validation.

We may revisit JSON Hyper-Schema at a later date.


Interested? Check out:

We encourage updating to the latest specification where possible, which is 2020-12.

Questions? Feeling helpful? Get involved on: