DocsJSON Schema 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
| keyword | change | notes |
|---|---|---|
"$comment" | added to Core | Intended for notes to schema maintainers, as opposed to "description" which is suitable for display to end users |
"if", "then", "else" | added to Validation | explicit conditional schema evaluation |
"readOnly" | moved from Hyper-Schema to Validation | not limited to hypermedia environments |
"writeOnly" | added to Validation | general write-only fields, including but not limited to passwords |
"contentMediaType" | moved from Hyper-Schema to Validation | formerly "media": {"type": "..."} |
"contentEncoding" | moved from Hyper-Schema to Validation | formerly "media": {"binaryEncoding": "..."} |
Note that the "content*" keywords do not require validation.
Formats¶
Numerous formats were added, clarified, or restored from older drafts.
| format | change | notes |
|---|---|---|
"iri" | added | I18N equivalent of "uri" |
"iri-reference" | added | I18N equivalent of "uri-reference" |
"uri-template" | noted IRI support | There is no separate IRI Template standard |
"idn-email" | added | I18N equivalent of "email" |
"idn-hostname" | added | I18N equivalent of "hostname" |
"json-pointer" | clarified | Use for string form only, not URI fragment |
"relative-json-pointer" | added | Revived Relative JSON Pointer draft |
"regex" | restored from draft-03 | ECMA 262 regular expressions |
"date" | restored from draft-03 | RFC 3339 "full-date" |
"time" | restored from draft-03 | RFC 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:
readOnlyandwriteOnlyshould be logically ORedexamplesshould 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 relation | change | notes |
|---|---|---|
| "describedBy" | no change | network-accessible URL |
| "profile" | removed; use "schema" | opaque identifying URI |
| "schema" | added | opaque 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.