Draft-07

Introduction

The JSON Schema Draft-07 introduces various updates to enhance the functionality of JSON Schemas in contrast to maintaining backward compatibility with Draft-06.

Draft-07 Documents

• Core: draft-handrews-json-schema-01 (changes)
• Validation: draft-handrews-json-schema-validation-01 (changes)
• Hyper-Schema: draft-handrews-json-schema-hyperschema-01 (changes)
• JSON Schema meta-schema
• JSON Hyper-Schema meta-schema
• JSON Hyper-Schema Link Description Object meta-schema
• JSON Hyper-Schema recommended output schema
• Relative JSON Pointer: draft-handrews-relative-json-pointer-01 (changes)
• Published: 19-March-2018

Obsolete Draft 7 Documents

These were updated without changing functionality or meta-schemas due to a few errors and unclear sections.

• Core: draft-handrews-json-schema-00 (changes)
• Validation: draft-handrews-json-schema-validation-00 (changes)
• Hyper-Schema: draft-handrews-json-schema-hyperschema-00 (changes)
• Relative JSON Pointer: draft-handrews-relative-json-pointer-00 (changes)

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
• Formats
• Classification of Keywords
• Collecting Annotation Values
• JSON Schema in Hypermedia Environments
  • Linking Instances and Schemas
  • Instance Media Type

Keywords

• No keywords changed behavior
• No keywords were removed
• Some keywords were moved from Hyper-Schema, and two of those were renamed

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

Formats

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

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:

• Applicability
• Assertions
• Annotations

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:

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

JSON Hyper-Schema Draft-07 Release Notes

JSON Hyper-Schema draft-07 completes the reworking of Hyper-Schema that was begun in draft-06.

Hyper-Schema is now solely focused on adding hyperlinks to JSON documents, so keywords used for other purposes (readOnly and media) have been moved to the Validation specification.

The new draft has been completely rewritten for clarity and accessibility, so it is best to simply approach it as a new proposal.

However, if you wish to migrate from an earlier draft, this page is a guide to the key changes. The additions, which are much more numerous, should be learned directly from the new specification until we can provide tutorials.

Note that draft-handrews-json-schema-hyperschema-00 has been replaced by draft-handrews-json-schema-hyperschema-01 in order to fix confusing bugs. The newer -01 draft is still considered to be draft-07. It now references the draft-07 meta-schema with the correct URI, among other typo fixes. There are no funcitonal changes between -00 and -01.

• Migrating from draft-06
• Migrating from draft-05
• Migrating from draft-04
  • GET
  • PUT
  • DELETE
  • POST
  • PATCH

Migrating from draft-06

No draft-06 features were changed, although two keywords were renamed for clarity and consistency:

• mediaType -> targetMediaType
• submissionEncType -> submissionMediaType

Additionally, hrefSchema was somewhat confusing, so a great deal more effort has gone into explaining how it works, and how it fits into the overall link resolution process.

Migrating from draft-05

See the draft-06 release notes for information related to draft-05.

Migrating from draft-04

In the ideal draft-07 world, links and operations are not the same concept. Using terminology borrowed from OpenAPI's Operation Object, HTTP methods are operations, and each link (as described by a single LDO) can support multiple operations.

Therefore, unlike draft-04, draft-07 hyper-schemas do not have separate links for each operation. This makes the migration guidelines below approximate at best.

For a more detailed explanation of how draft-04's method and targetSchema were typically used to create single-operation links, and how that poses a challenge for migrating to multi-operation links, see the draft-06 release notes. Those release notes also explain what happened to the link relations defined in draft-04 and subsequently removed, and the changes in how the instance base URI is determined.

Beyond those changes, a minimal migration would be something along the following lines, although the intentional lack of explicit response descriptions (except when the response happens to be a representation of the target resource) means that some uses of draft-04 do not have direct analogues in draft-07.

Any keyword not mentioned in a list below is unchanged for that link operation.

GET

• "method": "GET" -> "targetHints": {"allow": ["GET"]}
• mediaType -> targetMediaType
• schema -> hrefSchema with parameters added to href
• encType -> drop if application/x-www-form-urlencoded, contact the mailing list otherwise

PUT

If you have a PUT link where schema/encType differ from targetSchema/mediaType, where targetSchema/mediaType describe a non-representation response, then those fields do not have a direct replacement.

• "method": "PUT" -> "targetHints": {"allow": ["PUT"]}
• schema -> targetSchema
• encType -> targetMediaType

DELETE

DELETE does not take a request payload, so schema and encType should be unused. If targetSchema and mediaType were being used for a response other than the just-deleted resource's representation, then they do not have a direct replacement.

• "method": "DELETE" -> "targetHints": {"allow": ["DELETE"]}
• mediaType -> targetMediaType (if describing the representation)

POST

In most cases, the response of a POST is not a representation of the target resource, but rather some sort of result or status of whatever the POST attempted to do. Therefore targetSchema and mediaType should almost certainly be dropped. Other than that:

• "method": "POST" -> "targetHints": {"allow": ["POST"]}
• schema -> submissionSchema
• encType -> submissionMediaType

PATCH

It was never entirely clear how to model a proper PATCH (that uses a patch media type rather than application/json in the request) in Hyper-Schema. One option was to treat it identically to PUT except with the patch media type in encType. Assuming that approach (and the same taregetSchema/mediaType caveats as for PUT):

• "method": "PATCH" -> "targetHints": {"allow": ["PATCH"]}
• schema -> targetSchema
• "encType": "..." -> "targetHints": {"accept-patch": "..."}

JSON Schema Release Notes

• JSON Hyper-Schema Release Notes

Note that the draft-handrews-*-00 versions of JSON Hyper-Schema and Relative JSON Pointer had confusing bugs, and have been replaced by draft-handrews-*-01 versions. The -00 versions may be found in the obsolete directory.