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
{{ message }}
This repository was archived by the owner on Nov 2, 2023. It is now read-only.
Copy file name to clipboardexpand all lines: documentation.md
+3-1
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,9 @@ layout: page
3
3
title: Specification
4
4
---
5
5
6
-
The latest Internet-Drafts at the IETF are the draft-wright-json-schema\*-01 documents, which correspond to the draft-06 meta-schemas. These were published on 2017-04-15. (Due to a change in authorship the I-D numbering was reset with the previous draft). The specification is split into three parts, Core, Validation, and Hyper-Schema:
6
+
The latest Internet-Drafts at the IETF are the draft-wright-json-schema\*-01 documents, which correspond to the draft-06 meta-schemas. These were published on 2017-04-15. (Due to a change in authorship the I-D numbering was reset with the previous draft). Please see the [release notes](draft-06/README.md) for more information on this release and information on migrating from previous drafts.
7
+
8
+
The specification is split into three parts, Core, Validation, and Hyper-Schema:
<!-- This note should be incorporated into **specification-links.md**, but there are outstanding PR changes against that file. Leaving here to prevent merge conflicts. -->
11
+
12
+
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. Most people find it easier to remember the sequential meta-schema numbers, so those are used throughout the site.
[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)
23
+
[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](../draft-05/README.md)
24
+
[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)
25
+
26
+
27
+
For JSON Hyper-Schema, the correspondences are:
28
+
29
+
Hyper-Schema IETF Draft | Hyper-Schema Meta-Schema URI
Copy file name to clipboardexpand all lines: draft-06/json-hyper-schema-migration-faq.md
+7-32
Original file line number
Diff line number
Diff line change
@@ -1,32 +1,13 @@
1
-
## FAQ for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06)
1
+
---
2
+
title: JSON Hyper-Schema Draft 6 migration FAQ
3
+
layout: page
4
+
---
2
5
3
-
*[**Q: What are the incompatible changes between draft-04 and draft-06?**](#changes)
4
-
*[**Q: What are key issues under consideraton for draft-07?**](#consideration)
5
-
*[**Q: Why were several major changes made to Hyper-Schema just before publication?**](#publication)
6
-
*[**Q: Why doesn't the spec mention or behave like HTML anymore?**](#html)
7
-
*[**Q: So how do I indicate which HTTP methods are supported on a link?**](#implicit)
8
-
*[**Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link?**](#explicit)
9
-
*[**Q: If `"targetSchema"` is not the response, how do I describe responses?**](#response)
6
+
FAQ for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06).
10
7
11
-
## _A note on draft naming and numbering:_
8
+
* TOC
9
+
{:toc}
12
10
13
-
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 hyper-schema, the correspondences are:
14
-
15
-
Hyper-Schema IETF Draft | Hyper-Schema Meta-Schema URI
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.
26
-
27
-
## Questions and Answers
28
-
29
-
<aid="changes"></a>
30
11
### Q: What are the incompatible changes between draft-04 and draft-06?
31
12
32
13
Between drafts 04 and 06 we undertook a major re-examining of Hyper-Schema, which has never been as widely adopted as JSON Schema Validation.
@@ -67,7 +48,6 @@ Draft-06 clarfies this usage and provides guidance on its use with different HTT
67
48
68
49
However, see also [#296](https://github.com/json-schema-org/json-schema-spec/issues/296) for a proposal for hinting at "Accept-Patch", which is needed to properly use `"targetSchema"` with HTTP PATCH.
69
50
70
-
<aid="consideration"></a>
71
51
### Q: What are key issues under consideraton for draft-07?
72
52
73
53
There are a number of relatively concrete proposals, although it is unlikely that all will be resolved in draft-07
@@ -92,12 +72,10 @@ Additionally, there are two further proposals for JSON Schema vocabularies which
92
72
*[Documentation](https://github.com/json-schema-org/json-schema-spec/issues/136), which could take over some static API description work
93
73
*[UI](https://github.com/json-schema-org/json-schema-spec/issues/67), which would deal with presentation issues for forms
94
74
95
-
<aid="publication"></a>
96
75
### Q: Why were several major changes made to Hyper-Schema just before publication?
97
76
98
77
A: During final review, it became apparent that there was no consensus on how to use the spec as written. The late changes were necessary to publish a spec with unambiguous meaning, so that we could get feedback on its contents rather than differing interpretations. Originally we attempted to simply clarify what was there, but then we realized there was no agreement on what was there in the first place.
99
78
100
-
<aid="html"></a>
101
79
### Q: Why doesn't the spec mention or behave like HTML anymore?
102
80
103
81
A: While there are [unresolved questions around HTML analogies](https://github.com/json-schema-org/json-schema-spec/issues/294), we came to a consensus that the existing analogies caused more harm than good, for two reasons:
@@ -120,7 +98,6 @@ Draft-05 tried to restore the draft-03 behavior of `"method"`, but feedback told
120
98
We could have switched by to draft-04's `"method"` behavior, but in addition to producing more confusion from all of the back and forth, the draft-04 approach to `"method"` was not consistent with the rest of the LDO design anyway. Most notably, it caused problems with the usage of `"targetSchema"` as described above.
121
99
122
100
123
-
<aid="implicit"></a>
124
101
### Q: So how do I indicate which HTTP methods are supported on a link?
125
102
126
103
A: Ideally, this is implicitly conveyed by your link relation type, which is the primary indicator of semantics across machine-oriented hypermedia in general. [RFC 5988](https://tools.ietf.org/html/rfc5988) provides guidance on creating custom (a.k.a. "extension") link relations.
@@ -129,12 +106,10 @@ Several URI schemes and namespaces, such as the [UUID namespace in the `urn:` sc
129
106
130
107
And of course, there are ways to detect this at runtime such as HTTP's `"Allow"` response header, or attempting a method and handling a `405 Method Not Allowed` error accordingly.
131
108
132
-
<aid="explicit"></a>
133
109
### Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link?
134
110
135
111
A: Pick a proposal such as [`"allow"`](https://github.com/json-schema-org/json-schema-spec/issues/73) or [`"usageHints"`](https://github.com/json-schema-org/json-schema-spec/issues/296) to implement as an extension keyword and let us know how it works for you. This will help us determine the right permanent solution in future drafts.
136
112
137
-
<aid="response"></a>
138
113
### Q: If `"targetSchema"` is not the response, how do I describe responses?
139
114
140
115
A: You should have hyper-schemas for your various success and error responses, but connecting them to links is is more of a documentation question than a usage question: each response will indicate its own schema, so you don't need to know it in advance at runtime.
Copy file name to clipboardexpand all lines: draft-06/json-schema-migration-faq.md
+9-27
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,13 @@
1
-
## FAQ for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06)
1
+
---
2
+
title: JSON Schema Draft 6 migration FAQ
3
+
layout: page
4
+
---
2
5
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
+
FAQ for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06).
6
7
7
-
## _A note on draft naming and numbering:_
8
+
* TOC
9
+
{:toc}
8
10
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:
[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
-
<aid="changes"></a>
26
11
### Q: What are the changes between draft-04 and draft-06?
27
12
28
13
#### Backwards-incompatible changes
@@ -59,21 +44,19 @@ When a relative path, fragment, or any other style of URI Reference (per RFC 398
59
44
60
45
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
46
62
-
<aid="draft05"></a>
63
47
### Q: What happened to draft-05?
64
48
65
49
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
50
67
51
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
52
69
-
<aid="addlprop"></a>
70
53
### Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`?
71
54
72
55
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
56
74
57
The difficulty is that if you attempt to do this:
75
58
76
-
```JSON
59
+
```json
77
60
{
78
61
"type": "object",
79
62
"allOf": [
@@ -103,7 +86,7 @@ So in this example, if the instance has a "bar" property, it will fail the first
103
86
104
87
A workaround is available with the new `"propertyNames"` keyword:
105
88
106
-
```JSON
89
+
```json
107
90
{
108
91
"type": "object",
109
92
"allOf": [
@@ -141,7 +124,6 @@ It does require duplicating the names, and the awkward use of both an `"allOf"`
141
124
142
125
_*TODO:* Link to all of the discussions about other use cases and proposed solutions._
143
126
144
-
<aid="consideration"></a>
145
127
### Q: What are key issues under consideraton for draft-07?
146
128
147
129
We are just starting to consider what to prioritize for the next draft.
0 commit comments