diff --git a/work-in-progress/WIP-json-schema-release-notes.md b/work-in-progress/WIP-json-schema-release-notes.md new file mode 100644 index 00000000..36fe86d9 --- /dev/null +++ b/work-in-progress/WIP-json-schema-release-notes.md @@ -0,0 +1,52 @@ +--- +title: JSON Schema Draft-07 Release Notes +layout: page +--- + +There are a few non-breaking changes with keywords being deprecated and slates +for removal, and a few newer keywords based on community feedback. Internally +there has been a lot of restructuring through a new concept called vocabularies, +but on the whole things are mostly the same. + +* TOC +{:toc} + +- Update to RFC 8359 for JSON specification +- Add the concept of formal vocabularies, and how they can be recognized through meta-schemas +- Formalized annotation collection +- Moved applicator keywords from the Validation specification as their own vocabulary +- Define "$ref" behavior in terms of the assertion, applicator, and annotation model +- Note undefined behavior for "$ref" targets involving unknown keywords +- Additional guidance on initial base URIs beyond network retrieval +- Allow "schema" media type parameter for "application/schema+json" + +### Keywords + +* Eight brand new keywords were added +* One keyword was renamed +* One keyword was split in half +* One keyword in Core changed behavior +* One keyword in Hyper-Schema changed behavior + +keyword | change | notes +---- | ---- | ---- +[`"definitions"`](json-schema-core.html#rfc.section.TODO) | **renamed** | use new "$defs" core keyword +[`"unevaluatedProperties" and "unevaluatedItems"`](json-schema-core.html#rfc.section.TODO) | **added** | +[`"$ref"`](json-schema-core.html#rfc.section.TODO) | **changed** | can now have siblings (keywords next to it) +[`"$defs"`](json-schema-core.html#rfc.section.10.TODO) | **added** | moved over to core from validation +`"dependencies"` | **removed** | use "dependentRequired" or "dependentSchemas" +[`"dependentRequired"`](json-schema-core.html#rfc.section.10.TODO) | **added** | added to core schema +[`"dependentSchemas"`](json-schema-core.html#rfc.section.10.TODO) | **added** | added to core schema +[`"minContains" and "maxContains"`](json-schema-validation.html#rfc.section.TODO) | added | +[`"contentSchema"`](json-schema-validation.html#rfc.section.TODO) | added | allows applying a schema to a string-encoded document +[`"deprecated"`](json-schema-validation.html#rfc.section.TODO) | added | +[`"rel"`](json-schema-hyperschema.html#rfc.section.TODO) | **changed** | Can now be an array of values instead of just a string + +### Formats + +Two formats were added. + +format | change | notes +---- | ---- | ---- +[`"uuid"`](json-schema-validation.html#rfc.section.7.3.5) | added | A string instance is valid against this attribute if it is a valid string representation of a UUID, according to RFC4122 +[`"duration"`](json-schema-validation.html#rfc.section.7.3.5) | added | The duration format is from the ISO 8601 ABNF as given in Appendix A of RFC 3339 diff --git a/work-in-progress/index.md b/work-in-progress/index.md index e9de7c52..820a38e3 100644 --- a/work-in-progress/index.md +++ b/work-in-progress/index.md @@ -7,20 +7,21 @@ permalink: /work-in-progress * TOC {:toc} -## The Next Draft (by whatever name) Is Ready for Final Pre-Publication Review! +## The Next Draft is Ready for Final Pre-Publication Review! The forthcoming draft is now feature-frozen and has gone through the initial four-week pre-publication review period. _**UPDATE: July 28th, 2019** We continue to incorporate feedback and clarify sections of the new draft. We expect to finally publish the draft during August._ +To see what changes are involved, read the [release notes](./WIP-json-schema-release-notes.md). + 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. +Work on the next draft will begin immediately after this one is published. ## What Is This Draft Called, Anyway? @@ -88,9 +89,9 @@ _**NOTE:** when published, the `.json` will be removed from the final URI_ * [WIP: meta/meta-data.json](/work-in-progress/meta/WIP-meta-data.json) (meta-data annotations, from the validation spec) * [WIP: meta/format.json](/work-in-progress/meta/WIP-format.json) (the format keyword, from the validation spec) * [WIP: meta/content.json](/work-in-progress/meta/WIP-content.json) (content keywords, from the validation spec) -* [WIP: meta/hyper-schema.json](/work-in-progress/meta/WIP-hyper-schema.json) (hyper-schema keywords, from the hyper-shema spec) +* [WIP: meta/hyper-schema.json](/work-in-progress/meta/WIP-hyper-schema.json) (hyper-schema keywords, from the hyper-schema spec) -### Output schema: +### Output Schema The new draft also introduces recommended output formats for reporting errors and annotations. @@ -100,12 +101,12 @@ _**NOTE:** when published, the `.json` will be removed from the final URI_ * [WIP: verbose-example.json](/work-in-progress/output/WIP-verbose-example.json) (example of the most verbose output format) * [WIP: hyper-schema.json](/work-in-progress/output/WIP-hyper-schema.json) (format used by the proposed hyper-schema test suite, and used in examples in the specification) -## Providing Feedback and Tracking Progress in GitHub +## Get Involved 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. +Note that _all drafts have Changelog appendices_, for a concise list of notable changes. * The active sources are on the ["master" branch of json-schema-org/json-schema-spec](https://github.com/json-schema-org/json-schema-spec) @@ -117,4 +118,3 @@ Note that _all drafts have Changelog appendicies_, for a concise list of notable * [file an issue](https://github.com/json-schema-org/json-schema-spec/issues/new?milestone=draft-08) or [join us on Slack](https://join.slack.com/t/json-schema/shared_invite/enQtMjk1NDcyNDI2NTAwLTcyYmYwMjdmMmUxNzZjYzIxNGU2YjdkNzdlOGZiNjIwNDI2M2Y3NmRkYjA4YmMwODMwYjgyOTFlNWZjZjAyNjg) to submit feedback _(technically there is also a [mailing list](https://groups.google.com/forum/#!forum/json-schema) but it gets very little traffic and is not closely monitored)_ -