diff --git a/draft/2019-09/release-notes.md b/draft/2019-09/release-notes.md index 0f5c933d..0583b94f 100644 --- a/draft/2019-09/release-notes.md +++ b/draft/2019-09/release-notes.md @@ -3,8 +3,6 @@ title: JSON Schema 2019-09 Release Notes layout: page --- -_NOTE: This page is still being written, and is currently a fairly minimal listing of changes._ - For the vast majority of schema authors, we hope that these changes are minimally disruptive. The most likely to be frustrating is that `format` is no longer treated as a validation assertion _by default_ (although it is still possible for an application or user to configure a validator to treat it as one). We decided this was acceptable because many schema authors are already extremely frustrated by its inconsistent behavior. diff --git a/draft/2020-12/release-notes.md b/draft/2020-12/release-notes.md index ed8cfc6e..977eabfb 100644 --- a/draft/2020-12/release-notes.md +++ b/draft/2020-12/release-notes.md @@ -2,7 +2,479 @@ title: JSON Schema 2020-12 Release Notes layout: page --- +The previous draft (2019-09) introduced a lot of new concepts including +`$recursiveRef`/`$recursiveAnchor`, `unevaluatedProperties`/`unevaluatedItems`, +vocabularies, and more. Since then, these new features have seen multiple +implementations and usage in real schemas. This draft is mostly dedicated to +changes related to applying the lessons we've learned about implementing and +using these new features in the wild. -_NOTE: This page is still being written._ +This document attempts to put information most useful to schema authors toward +the top and information for implementation authors toward the bottom. -You can find a minimal changelog at the end of the specification documents themselves. \ No newline at end of file +## Changes to items and additionalItems +The keywords used for defining arrays and tuples have been redesigned to help +lower the learning curve for JSON Schema. Since the `items` keyword was used for +both types, we would often see people mistakenly defining a tuple when they +meant to define an array and not understand why only the first item in the array +was validating. + +The `items` and `additionalItems` keywords have been replaced with `prefixItems` +and `items` where `prefixItems` has the same functionality as the +array-of-schemas for of the old `items` and the new `items` keyword has the same +functionality as the old `additionalItems` keyword. + +Although the meaning of `items` has changed, the syntax for defining arrays +remains the same. Only the syntax for defining tuples has changed. The idea is +that an array has items (`items`) and optionally has some positionally defined +items that come before the normal items (`prefixItems`). + +Here are some examples to illustrate the changes. + +### Open tuple +
Draft 2019-09 | +Draft 2020-12 | +
---|---|
+ { + "items": [ + { "$ref": "#/$defs/foo" }, + { "$ref": "#/$defs/bar" } + ] +}+ |
+
+ { + "prefixItems": [ + { "$ref": "#/$defs/foo" }, + { "$ref": "#/$defs/bar" } + ] +}+ |
+
Draft 2019-09 | +Draft 2020-12 | +
---|---|
+ { + "items": [ + { "$ref": "#/$defs/foo" }, + { "$ref": "#/$defs/bar" } + ], + "additionalItems": false +}+ |
+
+ { + "prefixItems": [ + { "$ref": "#/$defs/foo" }, + { "$ref": "#/$defs/bar" } + ], + "items": false +}+ |
+
Draft 2019-09 | +Draft 2020-12 | +
---|---|
+ { + "items": [ + { "$ref": "#/$defs/foo" }, + { "$ref": "#/$defs/bar" } + ], + "additionalItems": { "$ref": "#/$defs/baz" } +}+ |
+
+ { + "prefixItems": [ + { "$ref": "#/$defs/foo" }, + { "$ref": "#/$defs/bar" } + ], + "items": { "$ref": "#/$defs/baz" } +}+ |
+
Draft 2019-09 | +Draft 2020-12 | +
---|---|
// tree schema, extensible +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "https://example.com/tree", + "$recursiveAnchor": true, + + "type": "object", + "properties": { + "data": true, + "children": { + "type": "array", + "items": { "$recursiveRef": "#" } + } + } +} + +// strict-tree schema, guards against misspelled properties +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "https://example.com/strict-tree", + "$recursiveAnchor": true, + + "$ref": "tree", + "unevaluatedProperties": false +} |
+ // tree schema, extensible +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.com/tree", + "$dynamicAnchor": "node", + + "type": "object", + "properties": { + "data": true, + "children": { + "type": "array", + "items": { "$dynamicRef": "#node" } + } + } +} + +// strict-tree schema, guards against misspelled properties +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.com/strict-tree", + "$dynamicAnchor": "node", + + "$ref": "tree", + "unevaluatedProperties": false +} |
+
Draft 2019-09 | +Draft 2020-12 | +
---|---|
{ + "type": "array", + "contains": { "type": "string" }, + "items": { + "anyOf": [ + { "type": "string" }, + { "type": "number" } + ] + } +} |
+ { + "type": "array", + "contains": { "type": "string" }, + "unevaluatedItems": { "type": "number" } +} + + + + + + |
+