Anatomy of a json schema - sgpinkus/json-schema GitHub Wiki

NOTE: This page was written around the time of Draft 03 and is not being updated.

A JSON Schema is a JSON Object, as defined by the JSON RFC. The simplest JSON Schema is:

{}

also called (quite obviously so) an empty schema.

Schemas can be nested. For instance, this is a legal JSON Schema:

{
    "title": "Parent",
    "properties": {
        "p": { "type": "string" }
    }
}

A parent schema is a schema which enclosing schema is itself. In the example above, the schema with name parent is a parent schema. { "type": "string" }, however, is not: its enclosing schema is the schema with name parent.

An instance is any JSON document to be processed by a JSON Schema. And it does mean any: null is a valid instance, so is true, so is 11.923, etc.

In the scope of JSON Schema, what is called members (ie, keys of an object) in the JSON RFC will be called keywords (or schema keywords).

Schema keywords can be further divided according to their purpose (OK, I made this up and this is not in the draft yet, but I think it is a decent way of sorting them out). Each purpose has its own, dedicated wiki page:

• [identifying keywords](identifying keywords): these keywords help identify schemas in a unique way, or find other schemas. There are three such keywords: $schema, $ref and id.
• [validation keywords](validation keywords): these keywords are used to verify the validity of instances against a schema.
• [documentation keywords](documentation keywords): these keywords add documentation to a JSON Schema. This documentation can be displayed to the user interactively (so that she understand the purpose of the data being produced) or used by developers to gain insight into the purpose of data structures.
• [hyperlink keywords](hyperlink keywords): these keywords describe relationships between instances and other resources, including data to submit with the request

Implementations are free to add support for keywords not defined here. However, it can be the case that one implementation "A" give this particular keyword one meaning and implmentation "B" another.

Therefore, it is recommended that unknown keywords be ignored. "Recommended" only because the draft does not actually specify a policy to handle them. In essence, this means that:

{ "foo": "bar" }

is equivalent to an empty schema. Ignoring unknown keywords (instead of raising an error, for instance) is also what allows such schemas to be written:

{
    "schema1": { "type": "string" },
    "schema2": { "type": "boolean" }
}