The current version is draft-07!

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

Advantages

JSON Schema

  • 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.

JSON Hyper-Schema

  • Make any JSON format a hypermedia format with no constraints on document structure
  • Allows use of URI Templates with instance data
  • Describe client data for use with links using JSON Schema.
  • Recognizes collections and collection items.

Project Status

Update as of 31 March 2019

You may be wondering what in the world is going on with this draft? The short version is: we are entering the home stretch. There are some ideas for simplifying $id that we are considering, and then there will be a final review period for feedback on overall flow and clarity.

As for the long version: The original intent was to publish by the time the previous draft by or at least soon after the current Core and Validation drafts expired on 20 September, 2018. The project is a volunteer project, and one editor was driving most of the large changes in this draft.

Unfortunately, that editor had a lot of Real Life Stuff(tm) to deal with this past year, including changing jobs (which put things on hold from about May through August or so) and then a run of minor health issues (which put things on hold from November through February). Other contributors made progress during those times,

As of March, everyone is back to working towards the publication of the draft as schedules permit.

We expect to publish a new round of drafts (Core, Validation, Hyper-Schema, Relative JSON Pointer) in the next month or two, and are actively working on the last few PRs. While the drafts are currently expired, they are still under active development. This project is staffed by volunteers, and life occasionally disregards IETF expiration schedules.

This draft has also taken more time than expected because it tackles deep, long-term issues that have long been a challenge for JSON Schema. This includes building in a formal extensibility mechanism so that we can more easily draw a line to finalize the contents of the Core and Validation specifications.

Progress on the next set of Internet-Drafts can be tracked on GitHub. The draft-08 milestone will track the evolving scope of the draft (although see issue #612 for a discussion of whether “draft-08” is the right name for this milestone).

The Path to Standardization

The JSON Schema project intends to shepherd all four draft series to RFC status. Currently, we are continuing to improve our self-published Internet-Drafts. The next step will be to get the drafts adopted by an IETF Working Group. We are actively investigating how to accomplish this.

If you have experience with such things and would like to help, please 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.

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:

{}

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.

More

Interested? Check out:

We encourage updating to the latest specification, as described by the draft-07 meta-schemas.

Questions? Feeling helpful? Get involved on: