Skip to content
This repository was archived by the owner on Nov 2, 2023. It is now read-only.

Commit 5083344

Browse files
handrewshandrews
committed
Update various pages for newly published draft.
1 parent 16a71b1 commit 5083344

File tree

4 files changed

+339
-84
lines changed

4 files changed

+339
-84
lines changed

‎draft/2019-09/release-notes.md

Lines changed: 34 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ title: JSON Schema Draft-2019/09 Release Notes
33
layout: page
44
---
55

6+
_NOTE: This page is still being written, and is currently a fairly minimal listing of changes._
7+
68
For the vast majority of schema authors, we hope that these changes are minimally disruptive.
79

810
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.
@@ -13,9 +15,9 @@ For implementors, there is a lot more to consider, and further guidance on imple
1315
{:toc}
1416

1517
For a basic list of changes to each document, see their change logs:
16-
* [Core](/work-in-progress/WIP-jsonschema-core.html#rfc.appendix.G)
17-
* [Validation](/work-in-progress/WIP-jsonschema-validation.html#rfc.appendix.C)
18-
* [Hyper-Schema](/work-in-progress/WIP-jsonschema-hyperschema.html#rfc.appendix.B)
18+
* [Core](/draft/2019-09/json-schema-core.html#rfc.appendix.G)
19+
* [Validation](/draft/2019-09/json-schema-validation.html#rfc.appendix.C)
20+
* [Hyper-Schema](/draft/2019-09/json-schema-hypermedia.html#rfc.appendix.B)
1921

2022
### Incompatible Changes
2123

@@ -33,60 +35,60 @@ The old syntax for these keywords is not an error (and the default meta-schema s
3335

3436
### Annotations, Errors, and Outputs
3537

36-
[Annotation keywords](/work-in-progress/WIP-jsonschema-core.html#rfc.section.7.7) such as `title`, `readOnly`, and `default` have always been a part of JSON Schema, but without any guidance on how to make use of them. This draft formalizes how implementations can make annotation information available to applications.
38+
[Annotation keywords](/draft/2019-09/json-schema-core.html#rfc.section.7.7) such as `title`, `readOnly`, and `default` have always been a part of JSON Schema, but without any guidance on how to make use of them. This draft formalizes how implementations can make annotation information available to applications.
3739

3840
Similarly, there has not previously been guidance on what constitutes useful error reporting when validation fails.
3941

40-
To solve both of these problems, we now recommend that implementations support one or more of standardized [output formats](/work-in-progress/WIP-jsonschema-core.html#rfc.section.10).
42+
To solve both of these problems, we now recommend that implementations support one or more of standardized [output formats](/draft/2019-09/json-schema-core.html#rfc.section.10).
4143

4244
### Keyword Changes
4345

44-
All keywords have now been organized into [vocabularies](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.1), with the Core and Validation specifications containing multiple vocabularies. In this process, some keywords have moved from Validation into Core.
46+
All keywords have now been organized into [vocabularies](/draft/2019-09/json-schema-core.html#rfc.section.8.1), with the Core and Validation specifications containing multiple vocabularies. In this process, some keywords have moved from Validation into Core.
4547

4648
#### Core Vocabulary
4749

48-
[Core Specification, Section 8](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8)
50+
[Core Specification, Section 8](/draft/2019-09/json-schema-core.html#rfc.section.8)
4951

5052
keyword | change | notes
5153
---- | ---- | ----
52-
[`$anchor`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.2.3) | **new** | Replaces the `#plain-name` form of `$id`, with a different syntax and approach
53-
[`$defs` (renamed from `definitions`)](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.2.5) | **renamed** | Note that the standard meta-schema still reserves `definitions` for backwards compatibility
54-
[`$id`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.2.2) | **changed** | Only URI-references without fragments are allowed; see `$anchor` for a replacement for plain-name fragments; all other fragments in `$id` had undefined behavior previously
55-
[`$recursiveAnchor` and `$recursiveRef`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.2.4.2) | **new** | Used for extending recursive schemas such as meta-schemas
56-
[`$ref`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.2.4) | **changed** | Other keywords are now allowed alongside of it
57-
[`$vocabulary`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.8.1) | **new** | Has effects only in meta-schemas, and is used to control what keywords an implementation must or can support in order to process a schema using that meta-schema
54+
[`$anchor`](/draft/2019-09/json-schema-core.html#rfc.section.8.2.3) | **new** | Replaces the `#plain-name` form of `$id`, with a different syntax and approach
55+
[`$defs` (renamed from `definitions`)](/draft/2019-09/json-schema-core.html#rfc.section.8.2.5) | **renamed** | Note that the standard meta-schema still reserves `definitions` for backwards compatibility
56+
[`$id`](/draft/2019-09/json-schema-core.html#rfc.section.8.2.2) | **changed** | Only URI-references without fragments are allowed; see `$anchor` for a replacement for plain-name fragments; all other fragments in `$id` had undefined behavior previously
57+
[`$recursiveAnchor` and `$recursiveRef`](/draft/2019-09/json-schema-core.html#rfc.section.8.2.4.2) | **new** | Used for extending recursive schemas such as meta-schemas
58+
[`$ref`](/draft/2019-09/json-schema-core.html#rfc.section.8.2.4) | **changed** | Other keywords are now allowed alongside of it
59+
[`$vocabulary`](/draft/2019-09/json-schema-core.html#rfc.section.8.1) | **new** | Has effects only in meta-schemas, and is used to control what keywords an implementation must or can support in order to process a schema using that meta-schema
5860

5961
#### Applicator Vocabulary
6062

61-
[Core Specification, Section 9](/work-in-progress/WIP-jsonschema-core.html#rfc.section.9)
63+
[Core Specification, Section 9](/draft/2019-09/json-schema-core.html#rfc.section.9)
6264

6365
These keywords were formerly found in the Validation Specification.
6466

6567
keyword | change | notes
6668
---- | ---- | ----
67-
[`dependentSchemas` (split from `dependencies`)](/work-in-progress/WIP-jsonschema-core.html#rfc.section.9.2.2.4) | **split** | This is the schema form of `dependencies`; note that the standard meta-schema still reserves `dependencies` for backwards compatibility
68-
[`unevaluatedItems`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.9.3.1.3) | **new** | Similar to `additionalItems`, but can "see" into subschemas and across references
69-
[`unevaluatedProperties`](/work-in-progress/WIP-jsonschema-core.html#rfc.section.9.3.2.4) | **new** | Similar to `additionalProperties`, but can "see" into subschemas and across references
69+
[`dependentSchemas` (split from `dependencies`)](/draft/2019-09/json-schema-core.html#rfc.section.9.2.2.4) | **split** | This is the schema form of `dependencies`; note that the standard meta-schema still reserves `dependencies` for backwards compatibility
70+
[`unevaluatedItems`](/draft/2019-09/json-schema-core.html#rfc.section.9.3.1.3) | **new** | Similar to `additionalItems`, but can "see" into subschemas and across references
71+
[`unevaluatedProperties`](/draft/2019-09/json-schema-core.html#rfc.section.9.3.2.4) | **new** | Similar to `additionalProperties`, but can "see" into subschemas and across references
7072

7173
The other applicator vocabulary keywords are `items`, `additionalItems`, `properties`, `patternProperties`, `additionalProperties`, `anyOf`, `allOf`, `oneOf`, `not`, `if`, `then`, `else`.
7274

7375
#### Validation Vocabulary
7476

75-
[Validation Specification, Section 6](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.6)
77+
[Validation Specification, Section 6](/draft/2019-09/json-schema-validation.html#rfc.section.6)
7678

7779
keyword | change | notes
7880
---- | ---- | ----
79-
[`dependentRequired` (split from `dependencies`)](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.6.5.4) | **split** | This is the string array form of `dependencies`; note that the standard meta-schema still reserves `dependencies` for backwards compatibility
80-
[`maxContains` and `minContains`](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.6.4.4) | **new** | Assertion for controlling how many times a subschema must be matched within an array
81+
[`dependentRequired` (split from `dependencies`)](/draft/2019-09/json-schema-validation.html#rfc.section.6.5.4) | **split** | This is the string array form of `dependencies`; note that the standard meta-schema still reserves `dependencies` for backwards compatibility
82+
[`maxContains` and `minContains`](/draft/2019-09/json-schema-validation.html#rfc.section.6.4.4) | **new** | Assertion for controlling how many times a subschema must be matched within an array
8183

8284

8385
#### Format Vocabulary
8486

85-
[Validation Specification, Section 7](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.7)
87+
[Validation Specification, Section 7](/draft/2019-09/json-schema-validation.html#rfc.section.7)
8688

8789
The `format` keywords has always been problematic due to its optional nature. There has never been a way to ensure that the implementation processing your schema supports `format` at all, or if it does, to what degree it validates each type of format. In theory, since each format references a standard specification, if a format is supported, it should behave consistently. In practice, this is not the case.
8890

89-
There are two ways for an application to validate formats: It can rely on a JSON Schema implementation to validate them (which may or may not have the expected results), or it can note where the `format` keyword has been used and perform its own validation based on that. This second approach is supported by treating `format` as an [annotation keyword](/work-in-progress/WIP-jsonschema-core.html#rfc.section.7.7) and supporting the [basic, detailed, or verbose output formats](/work-in-progress/WIP-jsonschema-core.html#rfc.section.10.4.2).
91+
There are two ways for an application to validate formats: It can rely on a JSON Schema implementation to validate them (which may or may not have the expected results), or it can note where the `format` keyword has been used and perform its own validation based on that. This second approach is supported by treating `format` as an [annotation keyword](/draft/2019-09/json-schema-core.html#rfc.section.7.7) and supporting the [basic, detailed, or verbose output formats](/draft/2019-09/json-schema-core.html#rfc.section.10.4.2).
9092

9193
To impose some predictability on this system, the behavior has changed in several ways, as illustrated below. The key difference here is that `format` validation is now predictably off by default, but can be configured to be turned on. In draft-07, it was on (but possibly unimplemented) by default and could be configured to be turned off.
9294

@@ -131,34 +133,34 @@ Additionally, two new formats were added, and a specification reference was upda
131133

132134
format | change | notes
133135
---- | ---- | ----
134-
[`"duration"`](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.7.3.1) | **added** | The duration format is from the ISO 8601 ABNF as given in Appendix A of RFC 3339
135-
[`"hostname"` and `"idn-hostname"`](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.7.3.3) | **updated** | Use RFC 1123 instead of RFC 1034; this allows for a leading digit
136-
[`"uuid"`](/work-in-progress/WIP-jsonschema-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
136+
[`"duration"`](/draft/2019-09/json-schema-validation.html#rfc.section.7.3.1) | **added** | The duration format is from the ISO 8601 ABNF as given in Appendix A of RFC 3339
137+
[`"hostname"` and `"idn-hostname"`](/draft/2019-09/json-schema-validation.html#rfc.section.7.3.3) | **updated** | Use RFC 1123 instead of RFC 1034; this allows for a leading digit
138+
[`"uuid"`](/draft/2019-09/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
137139

138140

139141
#### Content Vocabulary
140142

141-
[Validation Specification, Section 8](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.8)
143+
[Validation Specification, Section 8](/draft/2019-09/json-schema-validation.html#rfc.section.8)
142144

143145
These keywords are now specified purely as annotations, and never assertions. Some guidance is provided around how an implementation can optionally offer further automatic processing of this information outside of the validation process.
144146

145147
keyword | change | notes
146148
---- | ---- | ----
147-
[`contentEncoding`](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.8.3) | **updated** | Encodings from RFC 4648 are now allowed, and take precedence over RFC 2045 when there is a difference
148-
[`contentSchema`](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.8.5) | **added** | Schema for use with the decoded content string; note that it is _not_ automatically applied as not all content media types can be understood in advance
149+
[`contentEncoding`](/draft/2019-09/json-schema-validation.html#rfc.section.8.3) | **updated** | Encodings from RFC 4648 are now allowed, and take precedence over RFC 2045 when there is a difference
150+
[`contentSchema`](/draft/2019-09/json-schema-validation.html#rfc.section.8.5) | **added** | Schema for use with the decoded content string; note that it is _not_ automatically applied as not all content media types can be understood in advance
149151

150152
#### Meta-Data Vocabulary
151153

152-
[Validation Specification, Section 9](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.9)
154+
[Validation Specification, Section 9](/draft/2019-09/json-schema-validation.html#rfc.section.9)
153155

154156
keyword | change | notes
155157
---- | ---- | ----
156-
[`deprecated`](/work-in-progress/WIP-jsonschema-validation.html#rfc.section.9.3) | **added** | Used to indicate that a field is deprecated in some application-specific manner
158+
[`deprecated`](/draft/2019-09/json-schema-validation.html#rfc.section.9.3) | **added** | Used to indicate that a field is deprecated in some application-specific manner
157159

158160
#### Hyper-Schema Vocabulary
159161

160-
[Hyper-Schema Specification, Sections 5 and 6](/work-in-progress/WIP-jsonschema-hyperschema.html#rfc.section.5)
162+
[Hyper-Schema Specification, Sections 5 and 6](/draft/2019-09/json-schema-hypermedia.html#rfc.section.5)
161163

162164
keyword | change | notes
163165
---- | ---- | ----
164-
[`rel`](/work-in-progress/WIP-jsonschema-hyperschema.html#rfc.section.6.2.1) | **changed** | Can now be an array of values instead of just a string
166+
[`rel`](/draft/2019-09/json-schema-hypermedia.html#rfc.section.6.2.1) | **changed** | Can now be an array of values instead of just a string

‎index.md

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ title: JSON Schema
44
permalink: /
55
---
66

7-
***The current version is [draft-07](specification.html)!***
8-
{: style="color:gray; font-size: 150%; text-align: center;"}
7+
**NEW DRAFT PUBLISHED!**
8+
{: style="color:red; font-size: 200%; text-align: center;"}
99

10-
***The next draft work-in-progress is [in final review](work-in-progress)!***
11-
{: style="color:red; font-size: 150%; text-align: center;"}
10+
The current version is [draft/2019-09](specification.html)!
11+
{: style="color:gray; font-size: 150%; text-align: center;"}
1212

1313
**JSON Schema** is a vocabulary that allows you to **annotate** and **validate** JSON documents.
1414

@@ -40,19 +40,9 @@ permalink: /
4040

4141
## Project Status
4242

43-
### Update as of 8 September 2019
44-
45-
***All PRs from our final review feedback for the next draft have been posted!***
46-
47-
_The draft will be published as soon as we have sufficient reviews from the spec team and/or implementation owners. As this is summer vacation season, that may still take a few weeks. As of September 8th, all but one team member have completed their reviews, and the last team member is now looking at the remaining PRs._
48-
49-
This draft has also taken more time than expected because it tackles deep, long-term issues that have long been a challenge for JSON Schema. This includes building in a formal extensibility mechanism so that we can more easily draw a line to finalize the contents of the Core and Validation specifications.
50-
51-
Additionally, numerous life issues reduced the availability of key contributors during the process.
52-
53-
And finally, the feedback process demonstrated that our first attempt at a publishable draft needed substantial additional work, adding another few months to the timeline.
43+
16 September 2019: Draft 2019-09 (formerly known as draft-08) has been published!
5444

55-
Since the most intractable problems are all addressed to one degree or another in this draft, we do not anticipate future drafts taking so long.
45+
See the [Specification page](specification.html) for details.
5646

5747
### The Path to Standardization
5848

0 commit comments

Comments
 (0)