Identifying keywords - sgpinkus/json-schema GitHub Wiki

There is a lot to say about $ref an id in particular, this page tries and extripates useful information for day-to-day use of JSON Schema. If you consider the wording and explanations in this section to be inappropriate, confusing or just plain wrong, please open an issue.

All of these three keywords ($schema, $ref and id) MUST be string values. These string values MUST be valid URIs.

This keyword helps to tell an implementation that the schema is meant to be valid, and validate, according to a current version of the JSON Schema specification. This is a URI. It is recommended at this stage that this URI have this value:

{
    "$schema": "http://json-schema.org/draft-03/schema"
}

$ref is a JSON Reference. A JSON Reference is a JSON Object with one member named $ref, and as described above, the value for this member MUST be a string and a valid URI.

An important thing to consider is that the JSON Reference draft says the following:

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

which means, if you see such a schema:

{
    "$ref": "foo://bar/baz",
    "minimum": 3
}

then you SHOULD NOT validate the current instance against the minimum keyword.

Moreover, there are traps which you must be aware of.

This keyword helps to identify a schema (even an enclosed schema) in a unique way.

Unfortunately, this keyword's description in the current draft is surprisingly vague. Please see this page for more information.