Describe and validate JSON documents

JSON schema is the standard vocabulary for describing JSON data.
It validates documents and provides a clear human- and machine- readable documentation.

Community¶

We have an active and growing community. All are welcome to be part of our community, help shape it, or simply observe. We want to keep our community welcoming and inclusive, so please read our JSON Schema Organizational Code of Conduct. (This is a combination of the Contributor Covenant and IETF BCP 54.) The JSON Schema team and community are here to help! At any point, feel free to join our Slack server. Our Slack server has limited history, so we also use GitHub Discussions. We monitor the jsonschema tag on StackOverflow.

👩‍💻

Office HoursOpen zoom meeting
every first Tuesday of the month at 15:00 UTC
and by appointment.

👷

Open Community Working MeetingsOpen zoom meeting
every Monday at 14:00 PT.

Open Slack WorkspaceDiscuss and ask questions about all JSON Schema related things.

💬

GitHub Community DiscussionsPersistent organization level JSON Schema related discussions.

Project Status¶

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

The 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 Links page for details about naming and numbering.

The Path to Standardization¶

The JSON Schema project intends to self-publish the two JSON Schema specifications with the OpenJS Foundation. For the Relative JSON Pointer specification, we will likely pursue an RFC with IETF.

We are currently working toward moving away from self-published Internet-Drafts.

In the meantime, you can find the latest release of specification as Internet-Drafts on the Specification page.

Note that normal Internet-Drafts expire after six months and are replaced by subsequent drafts. Neither of those properties apply to JSON Schema. JSON Schema uses Internet-Drafts as production release documents, not as drafts, and each release is a distinct version of JSON Schema. That means that our releases remain relevant as long as they continue to be used in production despite what the document declares as its expiration.

Use of the draft designation¶

Releases of the JSON schema specification and meta schemas use the draft designation primarily for historical reasons stemming from the relationship of this specification to IETF (explained here). The use of this designation will not continue in future releases.

The JSON schema project recognizes, condones, and advocates for the use of the JSON schema standard in production.

Each release of the JSON schema specification is treated as a production release by the JSON schema project. All changes in each new release are made judiciously, with great care, thorough review and careful consideration of how the changes will impact existing users and implementations of the JSON schema specification.

Similarly to most specifications, the JSON schema specification will continue to evolve, and not all releases will be backwards compatible. The intention, particularly for vocabularies such as validation which have been widely implemented, is to remain as compatible as possible from release to release. However, major changes can still occur given a clear enough need validated with the user community.

Quickstart¶

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:

schema

1
{}

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:

schema

1
{2
  "type": "string"3
}

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.

Latest version of JSON Schema¶

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