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

Commit 190d0be

Browse files
handrewshandrews
committed
Created FAQ: draft-wright-json-schema[-validation]-01 (markdown)
1 parent 18d4ee9 commit 190d0be

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

‎FAQ:-draft-wright-json-schema[-validation]-01.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
## FAQ for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06)
2+
3+
* [**Q: What are the changes between draft-04 and draft-06?**](#changes)
4+
* [**Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`?](#addlprop)
5+
* [**Q: What are key issues under consideraton for draft-07?**](#consideration)
6+
7+
## _A note on draft naming and numbering:_
8+
9+
IETF Internet-Drafts (I-Ds) are named with the editor's name and a sequential number which resets with each new editor. Meta-schemas are numbered sequentially. Additionally, drafts 00-03 used one document for all three current specs. So, for core and validation, the correspondences are:
10+
11+
Core/Validation IETF Drafts | Meta-Schema URI
12+
---- | ----
13+
[draft-zyp-json-schema-00](https://tools.ietf.org/html/draft-zyp-json-schema-00) | [http://json-schema.org/draft-00/schema#](http://json-schema.org/draft-00/hyper-schema#)
14+
[draft-zyp-json-schema-01](https://tools.ietf.org/html/draft-zyp-json-schema-01) | [http://json-schema.org/draft-01/schema#](http://json-schema.org/draft-01/hyper-schema#)
15+
[draft-zyp-json-schema-02](https://tools.ietf.org/html/draft-zyp-json-schema-02) | [http://json-schema.org/draft-02/schema#](http://json-schema.org/draft-02/hyper-schema#)
16+
[draft-zyp-json-schema-03](https://tools.ietf.org/html/draft-zyp-json-schema-03) | [http://json-schema.org/draft-03/schema#](http://json-schema.org/draft-03/hyper-schema#)
17+
[draft-zyp-json-schema-04](https://tools.ietf.org/html/draft-zyp-json-schema-04) and [draft-fge-json-schema-validation-00](https://tools.ietf.org/html/draft-fge-json-schema-validation-00) | [http://json-schema.org/draft-04/hyper-schema#](http://json-schema.org/draft-04/schema#)
18+
[draft-wright-json-schema-00](https://tools.ietf.org/html/draft-wright-json-schema-00) and [draft-wright-json-schema-validation-00](https://tools.ietf.org/html/draft-wright-json-schema-validation-00) | draft-05; [not published](https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links)
19+
[draft-wright-json-schema-01](https://tools.ietf.org/html/draft-wright-json-schema-01) and [draft-wright-json-schema-validation-01](https://tools.ietf.org/html/draft-wright-json-schema-validation-01) | [http://json-schema.org/draft-06/schema#](http://json-schema.org/draft-06/hyper-schema#)
20+
21+
Most people find it easier to remember the sequential meta-schema numbers, so this FAQ will use those, including draft-05 for draft-wright-json-schema-hyperschema-00.
22+
23+
## Questions and Answers
24+
25+
<a id="changes"></a>
26+
### Q: What are the changes between draft-04 and draft-06?
27+
28+
#### Backwards-incompatible changes
29+
30+
keyword | change | consequence
31+
---- | ---- | ----
32+
`"id"` | replaced by `"$id"` | no longer easily confused with instance properties named `"id"`
33+
`"$id"` | replaces `"id"` | behavior is identical, `$` prefix matches the other two core keywords
34+
`"$ref"` | only allowed where a schema is expected | it is now possible to describe instance properties named `"$ref"`
35+
`"exclusiveMinimum"` and `"exclusiveMaximum"` | changed from a boolean to a number to be consistent with the principle of keyword independence | wherever one of these would be true before, change the value to the corresponding `"minimum"` or `"maximum"` value and remove the `"minimum"`/`"maximum"` keyword
36+
37+
#### Additions and backwards-compatible changes
38+
39+
keyword | change | consequence
40+
---- | ---- | ----
41+
booleans as schemas | allowable anywhere, not just `"additionalProperties"` and `"additionalItems"` | `true` is equivalent to `{}`, `false` is equivalent to `{"not": {}}`, but the intent is more clear and implementations can optimize these cases more easily
42+
`"propertyNames"` | added | takes a schema which validates the *names* of all properties rather than their values
43+
`"contains"` | added | array keyword that passes validation if its schema validates at least one array item
44+
`"const"` | added | more readible form of a one-element `"enum"`
45+
`"required"` | allows an empty array | an empty array indicates that no properties are required
46+
`"dependencies"` | allows an empty array for property dependencies | an empty array indicates that there are no dependencies for the given property
47+
`"format": "uri-reference"` | added | allows relative URI references per RFC 3986; see the section below about `"uri"` as a format
48+
`"format": "uri-template"` | added | indicates an RFC 6570 conforming URI Template value, as is used in JSON Hyper-Schema for `"href"`
49+
`"format": "json-pointer"` | added | indicates a JSON Pointer value such as `/foo/bar`; do _not_ use this for JSON Pointer URI fragments such as `#/foo/bar`: the proper format for those is `"uri-reference"`
50+
`"examples"` | added | array of examples with no validation effect; the value of `"default"` is usable as an example without repeating it under this keyword
51+
52+
#### Formats: `"uri"` vs `"uri-reference"`
53+
54+
While not technically a change, the behavior of the `"uri"` format was not clearly explained and often implemented and used incorrectly (including in the draft-04 meta-schema).
55+
56+
`"uri"` should only be used when an absolute URI (starting with a scheme) is required.
57+
58+
When a relative path, fragment, or any other style of URI Reference (per RFC 3986) is allowable, use `"uri-reference"`.
59+
60+
Implementations offering a translation from draft-04 to draft-06 may want to offer an option to convert `"uri"` formats to `"uri-reference"`, although any such option should be disable by default for strict conformance.
61+
62+
<a id="draft05"></a>
63+
### Q: What happened to draft-05?
64+
65+
The draft-05 core and validation specifications were intended to be more clear and readible rewrites of draft-04, to give us a strong base for draft-06 changes. Implementors should **not** implement or advertise support for "draft-05".
66+
67+
Implementations that supported "draft-05" by implementing proposals from right after the publication of draft-04 should either remove that support or give it a different name to avoid confusion.
68+
69+
<a id="addlprop"></a>
70+
### Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`?
71+
72+
There are several competing proposals for making the re-use of schemas that set `"additionalProperties"` to something other than `true`. Most people specifically care about the case where it is `false`, but the same behavior occurs with any non-`true` value.
73+
74+
The difficulty is that if you attempt to do this:
75+
76+
```JSON
77+
{
78+
"type": "object",
79+
"allOf": [
80+
{"$ref": "#/definitions/foo"},
81+
{"$ref": "#/definitions/bar"}
82+
],
83+
"definitions": {
84+
"foo": {
85+
"properties": {
86+
"foo": {"type": "string"}
87+
},
88+
"additionalProperties": false
89+
},
90+
"bar": {
91+
"properties": {
92+
"bar": {"type": "number"}
93+
},
94+
"additionalProperties": false
95+
}
96+
}
97+
}
98+
```
99+
100+
validation will always fail for any non-empty object instance. `"additionalProperties"` only knows about immediately adjacent `"properties"` and `"patternProperties"`, in order to ensure that each subschema means the same thing whether it is being used with another subschema or on its own.
101+
102+
So in this example, if the instance has a "bar" property, it will fail the first subschema because "bar" is not "foo". If it has a "foo" property, it will fail the second subschema because "foo" is not "bar". And any other property will fail both schemas.
103+
104+
A workaround is available with the new `"propertyNames"` keyword:
105+
106+
```JSON
107+
{
108+
"type": "object",
109+
"allOf": [
110+
{"$ref": "#/definitions/foo"},
111+
{"$ref": "#/definitions/bar"}
112+
],
113+
"anyOf": [
114+
{"$ref": "#/definitions/fooNames"},
115+
{"$ref": "#/definitions/barNames"}
116+
],
117+
"definitions": {
118+
"foo": {
119+
"properties": {
120+
"foo": {"type": "string"}
121+
}
122+
},
123+
"fooNames": {
124+
"propertyNames": {"enum": ["foo"]}
125+
},
126+
"bar": {
127+
"properties": {
128+
"bar": {"type": "number"}
129+
}
130+
},
131+
"barNames": {
132+
"propertyNames": {"enum": ["bar"]}
133+
}
134+
}
135+
}
136+
```
137+
138+
This will allow an object with either "foo" or "bar" or both, but will fail validation if any other property is present. The `"allOf"` ensures that "foo" and "bar" will each be validated correctly if present, while the `"anyOf"` allows for properties with names in either allowed set, but forbids properties that are not listed in at least one set.
139+
140+
It does require duplicating the names, and the awkward use of both an `"allOf"` and `"anyOf"`, but it is less repetition than other options, and can be re-used fairly robustly even if the "foo" and "bar" schemas are in separate files managed by a different person or organization.
141+
142+
_*TODO:* Link to all of the discussions about other use cases and proposed solutions._
143+
144+
<a id="consideration"></a>
145+
### Q: What are key issues under consideraton for draft-07?
146+
147+
We are just starting to consider what to prioritize for the next draft.
148+
149+
There are only some fairly minor items to consider for the core specification, so we'd like to wrap that up and get it ready for submission to a working group. The question of which link relation to use for connecting schemas to instances is the main one.
150+
151+
For validation, there are a number of competing proposals. We will update this document as we get agreement on priorities.

0 commit comments

Comments
 (0)