The Next Draft (by whatever name) Is Ready for Final Pre-Publication Review!

The forthcoming draft is now feature-frozen and entering the final four-week feedback period before publication. This final review will last from May 27th to June 24th, 2019.

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.

What Is This Draft Called, Anyway?

We have typically referred to this as draft-08, following our own convention of just incrementing the draft number for meta-schemas regardless of the IETF identifier.

However, this is frowned upon by the IETF and has in fact been a source of confusion. It worked well up to and including draft-04, as even after the split into multiple documents, draft-zyp-json-schema-04 (the core spec) at least ended in -04! Unfortunately, after that point, the numbers stopped matching in any way.

Assuming this new draft gets published more or less as presented in this WIP, and by the end of June, it will be:

  • IETF identifiers: draft-handrews-*-02
  • Meta-schema identifiers: draft/2019-06

Meta-schemas will now be identified with dates, which can be correlated with the publication and expiration dates of the IETF documents. This will make it more clear when a bugfix meta-schema is produced, and also make it more obvious that the IETF and meta-schema identifiers are not expected to match exactly.

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.

Specifications:

As always, these are the actual normative documents:

NOTE: Links to meta-schemas and among the drafts will not work correctly in these review copies.

General use meta-schemas:

These are the traditional non-normative meta-schemas, which serve the same purpose as in previous drafts, although their internal structure is different.

NOTE: when published, the .json will be removed from the final URI

Single-vocabulary meta-schemas:

The new draft introduces the concept of modular vocabularies. Most schema authors will not directly reference these meta-schemas. Instead, they are combined in useful ways by the general use meta-schemas. However, those wishing to build custom meta-schemas may find it useful to choose different subsets of the standard keywords depending on the custom meta-schema’s intended purpose.

NOTE: when published, the .json will be removed from the final URI

Output schema:

The new draft also introduces recommended output formats for reporting errors and annotations.

NOTE: when published, the .json will be removed from the final URI

Providing Feedback and Tracking Progress in GitHub

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.