Specification

Draft-07 Release Notes

For the Core and Validation specifications, draft-07 is a relatively minor update. In terms of validation keywords and outcomes, it is fully backwards-compatible with draft-06.

Some differences exist with keywords moved over from Hyper-Schema, and with how instances and schemas are recommended to be linked together. Finally, the process of collecting annotation keyword values has been defined more clearly than before.

Keywords

  • No keywords changed behavior
  • No keywords were removed
  • Some keywords were moved from Hyper-Schema, and two of those were renamed
keywordchangenotes
["$comment"](../../draft-07/json-schema-core.html#rfc.section.9)added to CoreIntended for notes to schema maintainers, as opposed to ["description"](../../draft-07/json-schema-validation.html#rfc.section.10.1) which is suitable for display to end users
["if", "then", "else"](../../draft-07/json-schema-validation.html#rfc.section.6.6)added to Validationexplicit conditional schema evaluation
["readOnly"](../../draft-07/json-schema-validation.html#rfc.section.10.3)moved from Hyper-Schema to Validationnot limited to hypermedia environments
["writeOnly"](../../draft-07/json-schema-validation.html#rfc.section.10.3)added to Validationgeneral write-only fields, including but not limited to passwords
["contentMediaType"](../../draft-07/json-schema-validation.html#rfc.section.8)moved from Hyper-Schema to Validationformerly ["media": {"type": "..."}](../../draft-06/json-schema-hypermedia.html#rfc.section.5.3)
["contentEncoding"](../../draft-07/json-schema-validation.html#rfc.section.8)moved from Hyper-Schema to Validationformerly ["media": {"binaryEncoding": "..."}](../../draft-06/json-schema-hypermedia.html#rfc.section.5.3)

Note that the "content*" keywords do not require validation.

Formats

Numerous formats were added, clarified, or restored from older drafts.

formatchangenotes
["iri"](../../draft-07/json-schema-validation.html#rfc.section.7.3.5)addedI18N equivalent of "uri"
["iri-reference"](../../draft-07/json-schema-validation.html#rfc.section.7.3.5)addedI18N equivalent of "uri-reference"
["uri-template"](../../draft-07/json-schema-validation.html#rfc.section.7.3.6)noted IRI supportThere is no separate IRI Template standard
["idn-email"](../../draft-07/json-schema-validation.html#rfc.section.7.3.2)addedI18N equivalent of "email"
["idn-hostname"](../../draft-07/json-schema-validation.html#rfc.section.7.3.3)addedI18N equivalent of "hostname"
["json-pointer"](../../draft-07/json-schema-validation.html#rfc.section.7.3.7)clarifiedUse for string form only, not URI fragment
["relative-json-pointer"](../../draft-07/json-schema-validation.html#rfc.section.7.3.7)addedRevived Relative JSON Pointer draft
["regex"](../../draft-07/json-schema-validation.html#rfc.section.7.3.8)restored from draft-03ECMA 262 regular expressions
["date"](../../draft-07/json-schema-validation.html#rfc.section.7.3.1)restored from draft-03RFC 3339 "full-date"
["time"](../../draft-07/json-schema-validation.html#rfc.section.7.3.1)restored from draft-03RFC 3339 "full-time"

All other RFC 3339 date, time, and duration names are reserved for future consideration. If added as extension formats, they SHOULD be implemented in a way that is compatible with their use in the RFC to ensure future compatibility.

Classification of Keywords

While it does not have a direct impact on the validation process, this set of drafts classifies keywords by their behavior. The names of these classifications are used throughout the documents, so they are useful to know:

Note that definitions does not fit any of these categories, nor do the dollar-prefixed Core keywords.

Collecting Annotation Values

Annotation keywords (formerly called metadata keywords now provide guidance on how to collect multiple values that apply to the same location in the instance. By default, all values that are not found within negated schemas are collected as an unordered set. The following exceptions are documented under the approprite keywords:

  • readOnly and writeOnly should be logically ORed
  • examples should be flattened into a single collected array

JSON Schema in Hypermedia Environments

These changes are not relevant to many Validation use cases, and are more of interest to Hyper-Schema users. However, even without Hyper-Schema, if you are accessing instance documents over HTTP or through other hypermedia environments, you may find this section useful.

Linking Instances and Schemas

After discussions with the author of the "profile" specification, we concluded that its use for JSON Schema was not correct. The new guidance for what relations to use to link instances to schemas is:

link relationchangenotes
"describedBy"no changenetwork-accessible URL
"profile"removed; use "schema"opaque identifying URI
"schema"addedopaque identifying URI

"schema", like "profile" in past drafts, can also be used as a media type parameter.

Instance Media Type

Changes in the section are more relevant to JSON Hyper-Schema than to Validation, but as they are part of the core specification, they are explained here.

Media types determine their own parameters, as well as their own URI fragment syntax(es). application/json does not allow any parameters or URI fragments.

application/schema-instance+json is an optional media type for use with instances that supports "schema" as a media type parameter, and allows for URI fragments using the JSON Pointer syntax.

Supporting "schema" as a media type parameter allows for schema-based content negotiation in hypermedia environments.

Supporting JSON Pointer URI fragments is primarily useful with JSON Hyper-Schema, as many URIs involved in hyper-schema usage originate from or point to locations within an instance document rather than the entire document.

Need Help?

Did you find these docs helpful?

Help us make our docs great!

At JSON Schema, we value docs contributions as much as every other type of contribution!

Still Need Help?

Learning JSON Schema is often confusing, but don't worry, we are here to help!.