Merge pull request #276 from json-schema-org/release-notes

WIP go at WIP Release Notes

Author: handrews

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

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)_
-