You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: index.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,11 +40,11 @@ permalink: /
40
40
41
41
## Project Status
42
42
43
-
### Update as of 26 Aug 2019
43
+
### Update as of 8 September 2019
44
44
45
45
***All PRs from our final review feedback for the next draft have been posted!***
46
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._
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
48
49
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.
There are a few non-breaking changes with keywords being deprecated and slates
7
-
for removal, and a few newer keywords based on community feedback. Internally
8
-
there has been a lot of restructuring through a new concept called vocabularies,
9
-
but on the whole things are mostly the same.
6
+
For the vast majority of schema authors, we hope that these changes are minimally disruptive. The most likely to be frustrating is `format`, which we decided was acceptable as many schema authors are already extremely frustrated by its inconsistent behavior.
7
+
8
+
For implementors, there is a lot more to consider, and further guidance on implementation topics will be forthcoming.
10
9
11
10
* TOC
12
11
{:toc}
13
12
14
-
- Update to RFC 8359 for JSON specification
15
-
- Add the concept of formal vocabularies, and how they can be recognized through meta-schemas
16
-
- Formalized annotation collection
17
-
- Moved applicator keywords from the Validation specification as their own vocabulary
18
-
- Define "$ref" behavior in terms of the assertion, applicator, and annotation model
19
-
- Note undefined behavior for "$ref" targets involving unknown keywords
20
-
- Additional guidance on initial base URIs beyond network retrieval
21
-
- Allow "schema" media type parameter for "application/schema+json"
13
+
For a basic list of changes to each document, see their change logs:
* By default, `format` is no longer an assertion. This has been done because the inconsistent implementation of `format` as an assertion has been an endless source of surprising problems for schema authors. The default behavior will now be predictable, if not ideal. There are several ways to turn on assertion functionality, as explained below. However, we recommend doing semantic validation in the application layer.
21
+
* Plain name fragments are no longer defined with `$id`, but instead with the new keyword `$anchor` (which has a different syntax).
22
+
*`$id` cannot contain a fragment anymore (except possibly an empty fragment, although that is discouraged).
23
+
* In cases where multiple URIs could be used for the same schema, some are now discouraged. These are believed to have rarely been used, as the behavior involved was fairly confusing and not well explained until the updated version of draft-07 (draft-handrews-json-schema-01). If this doesn't mean much to you, you are probably safe.
24
+
25
+
### Semi-incompatible Changes
26
+
27
+
The old syntax for these keywords is not an error (and the default meta-schema still validates them), so implementations can therefore offer a compatibility mode. However, migrating to the new keywords is straightforward and should be preferred.
28
+
29
+
*`definitions` is now `$defs`
30
+
*`dependencies` has been split into `dependentSchemas` and `dependentRequired`
31
+
32
+
### Annotations, Errors, and Outputs
33
+
34
+
[Annotation keywords](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.
35
+
36
+
Similarly, there has not previously been guidance on what constitutes useful error reporting when validation fails.
37
+
38
+
To solve both of these problems, we now recommend that implementations support one or more of standardized [output formats](WIP-jsonschema-core.html#rfc.section.10).
39
+
40
+
### Keyword Changes
41
+
42
+
All keywords have now been organized into [vocabularies](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.
[`$anchor`](WIP-jsonschema-core.html#rfc.section.8.2.3) | **new** | Replaces the `#plain-name` form of `$id`, with a different syntax and approach
51
+
[`$defs` (renamed from `definitions`)](WIP-jsonschema-core.html#rfc.section.8.2.5) | **renamed** | Note that the standard meta-schema still reserves `definitions` for backwards compatibility
52
+
[`$id`](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
53
+
[`$recursiveAnchor` and `$recursiveRef`](WIP-jsonschema-core.html#rfc.section.8.2.4.2) | **new** | Used for extending recursive schemas such as meta-schemas
54
+
[`$ref`] | **changed** | Other keywords are now allowed alongside of it
55
+
[`$vocabulary`](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
[`"rel"`](json-schema-hyperschema.html#rfc.section.TODO) | **changed** | Can now be an array of values instead of just a string
44
-
45
-
### Formats
46
-
47
-
Two formats were added.
65
+
[`dependentSchemas` (split from `dependencies`)](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
66
+
[`unevaluatedItems`](WIP-jsonschema-core.html#rfc.section.9.3.1.3) | **new** | Similar to `additionalItems`, but can "see" into subschemas and across references
67
+
[`unevaluatedProperties`](WIP-jsonschema-core.html#rfc.section.9.3.2.4) | **new** | Similar to `additionalProperties`, but can "see" into subschemas and across references
68
+
69
+
The other applicator vocabulary keywords are `items`, `additionalItems`, `properties`, `patternProperties`, `additionalProperties`, `anyOf`, `allOf`, `oneOf`, `not`, `if`, `then`, `else`.
[`dependentRequired` (split from `dependencies`)](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
78
+
[`maxContains` and `minContains`](WIP-jsonschema-validation.html#rfc.section.6.4.4) | **new** | Assertion for controlling how many times a subschema must be matched within an array
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.
86
+
87
+
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](WIP-jsonschema-core.html#rfc.section.7.7) and supporting the [basic, detailed, or verbose output formats](WIP-jsonschema-core.html#rfc.section.10.4.2).
88
+
89
+
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.
90
+
91
+
In the following charts, the "supported" column refers to whether and (for `2019-09`) to what degree the implementation claims to support the `format` keyword. The "configuration" column refers to whether some non-default behavior for `format` is configured somehow (in a configuration file, or through a command-line option, or whatever).
92
+
93
+
**Summary of draft-07 behavior**
94
+
95
+
supported | configuration | outcome
96
+
----------- | ------------- | -------------
97
+
no | n/a | not validated
98
+
yes | _default_ (on)| inconsistently validated
99
+
yes | off | not validated
100
+
101
+
Obviously, each implementation will behave consistently from schema to schema, although some formats may be supported more thoroughly than others despite the wording in the specification. However, complex formats are, in practice, supported to different degrees in each implementation. If they are supported at all.
102
+
103
+
**Summary of draft/2019-09 behavior**
104
+
105
+
The goal with this draft is to make the default behavior predictable, with the inconsistent behavior as an opt-in feature. This is not entirely satisfactory, but we feel that it is a good first step to reduce the number of complaints seen around surprising results. This way, there should at least be fewer surprises.
106
+
107
+
* "best effort" validation is a fairly weak requirement, which matches how things work in practice today. Simple formats are probably fully valid, complex formats may be minimally validated or even not validated at all.
108
+
109
+
* "full syntax" validation means that you can expect a reasonably thorough syntactic validation, probably corresponding to whatever commonly available libraries can do in the implementation language. For formats such as IP addresses and dates, this is expected to be complete validation. For more complex formats such as email addresses, support will probably still vary significantly. It's unclear how many implementations have ever provided this level of support.
110
+
111
+
* An outcome of _vocabulary error_ means that the implementation will refuse to process the schema as it cannot satisfy the vocabulary requirement.
best effort | _default_ (off)| false | not validated
118
+
best effort | _default_ (off)| true | _vocabulary error_
119
+
best effort | on | false | best effort validation
120
+
best effort | on | true | _vocabulary error_
121
+
full syntax | _default_ (off)| false | not validated
122
+
full syntax | _default_ (off)| true | full syntax validation
123
+
full syntax | on | false | full syntax validation
124
+
full syntax | on | true | full syntax validation
125
+
126
+
Note that, given that almost no draft-07 or earlier implementations have offered strict and complete validation of every single format, it seems unlikely that any implementations will support option 3 option in practice.
127
+
128
+
Additionally, two new formats were added, and a specification reference was updated:
48
129
49
130
format | change | notes
50
131
---- | ---- | ----
51
-
[`"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
52
-
[`"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
132
+
[`"duration"`](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
133
+
[`"hostname"` and `"idn-hostname"`](WIP-jsonschema-validation.html#rfc.section.7.3.3) | **updated** | Use RFC 1123 instead of RFC 1034; this allows for a leading digit
134
+
[`"uuid"`](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
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.
142
+
143
+
keyword | change | notes
144
+
---- | ---- | ----
145
+
[`contentEncoding`](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
146
+
[`contentSchema`](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
[`deprecated`](WIP-jsonschema-validation.html#rfc.section.9.3) | **added** | Used to indicate that a field is deprecated in some application-specific manner
155
+
156
+
#### Hyper-Schema Vocabulary
157
+
158
+
[Hyper-Schema Specification, Sections 5 and 6](WIP-jsonschema-hyperschema.html#rfc.section.5)
159
+
160
+
keyword | change | notes
161
+
---- | ---- | ----
162
+
[`rel`](WIP-jsonschema-hyperschema.html#rfc.section.6.2.1) | **changed** | Can now be an array of values instead of just a string
0 commit comments