The next draft (informally known as draft-07, formal IETF draft names to be determined) is now feature-frozen and entering the final feedback month before publication. The feedback period will last from October 20th to November 20th, 2017.

The timeline may be compressed if, after at least two weeks, there is a clear consensus that the drafts are solid and it would be best to publish sooner rather than later.

The following sorts of feedback are particularly desired:

  • Clarity, readability, and accessibility to new readers
  • Contradictions, inconsistencies and other bugs
  • Anything so egregious that implementation would be infeasible or impossible

New features or major changes to existing features will be deferred to a future draft, and work on the next draft will begin immediately after this one is published.

Pre-Built Review Documents

To encourage as many reviewers as possible, pre-built documents are available. These may slightly lag those in the GitHub repository, although all efforts will be made to keep them in sync during the review period. After the review period, these will be removed. In particular, using “WORK IN PROGRESS” meta-schemas is not allowed and will break as soon as the files are moved to their permanent homes.

Providing Feedback and Tracking Progress in GitHub

Summary of Changes

The primary focus of this draft has been JSON Hyper-Schema, which has been given a top-to-bottom rewrite in addition to numerous new features. As part of this, we have (with the original author’s permission), revived the Relative JSON Pointer proposal to be submitted alongside of hyper-schema.

In the course of that rewrite, several concepts that apply across all JSON Schema specifications became more clear, so in addition to new keywords in both Core and Validation, some of the introductory and other text has been reworked to fit into the new conceptual model.

We are particularly interested in feedback on whether the wording and concepts is an improvement in terms of how easy it is to understand and learn the specifications.

Note that all drafts have Changelog appendicies, for a concise list of notable changes.

Changes to Concepts

These are properly explained in the documents as noted. They are listed here to highlight their importance: If you read the drafts and do not understand these concepts, please file an issue or let us know on the mailing list.

  • applicability (defined in the validation spec)
  • assertions (defined in the validation spec, also mentioned in core)
  • true and false as trivial assertions (explained in core)
  • annotations (defined in the validation spec)
  • generic user agent (defined in hyper-schema)
  • client application and client input (defined in hyper-schema)

Changes to Specification Boundaries

The readOnly and media keywords, previously in Hyper-Schema, are often used (or people ask about using them) outside of Hyper-Schema. As a result, they have been moved to the validation spec:

  • readOnly is now a metadata keyword in the validation spec
  • media and its type and binaryEncoding keywords get their own validation spec section as contentMediaType and contentEncoding

Hyper-schema now solely describes the Link Description Object (LDO), plus the two keywords (base and links) necessary to connect the LDO to schemas.

Changes to the Core Specification

  • application/schema-instance+json optional instance media type
  • Proposed “schema” link relation type in place of using “profile”
  • Added $comment (also added to Hyper-Schema’s LDO)
  • Better wording around $id and fragments
  • Note the challenges of extending meta-schemas more clearly

Changes to the Validation Specification

Only if/then/else is a mandatory new implementation requirement. Everything else is either an annotation (no defined requirements) or gives implementations the option to not implement validation (format and content keywords).

  • Added if, then, and else
  • Added many new formats, clarified the “json-pointer” format
  • Added writeOnly alongside readOnly (moved from Hyper-Schema)
  • Moved the hyper-schema media object to the content* keywords in validation

Changes to the Hyper-Schema specification

Basically everything is different. It’s probably best to just read it top to bottom and pretend you’ve never heard of it before.

  • Added overview explaining the general purpose and scope
  • Aligned LDO with how links are described in RFC 8288
  • Context adjustment with anchor and anchorPointers
  • Pseudocode specification for URI Template resolution
  • templatePointers and templateRequired added to URI Template resolution process
  • mediaType and submissionEncType are now targetMediaType and submissionMediaType
  • targetHints and headerSchema for working with HTTP request and response headers
  • HTTP guidance has its own section
  • API usage has an appendix, including a subsection on static docs and code
  • Collections and items are recognizable based on link relation types

Known Issues

  • Hyper-Schema needs a lot more examples (suggestions encouraged!)
  • Hyper-Schema examples would be better if they fit together to tell a single story
  • Hyper-Schema needs to be consistent about cross-references

The primary author of this draft (and this page) notoriously struggles to write effective examples. Help on this aspect of the spec would be very much appreciated.