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: draft-06/json-hyper-schema-migration-faq.md
+4-4
Original file line number
Diff line number
Diff line change
@@ -44,11 +44,11 @@ While `"targetSchema"` did not change its meaning in either recent draft, it has
44
44
45
45
Due to draft-04 emphasizing individual HTTP methods as `"method"` values, many users interpreted `"targetSchema"` as a hint of the response to the method in `"method"`. This was never correct; all drafts define this keyword as describing the representation of the target resource, which appears as a response to HTTP GET, but may or may not appear in other responses.
46
46
47
-
Draft-06 clarfies this usage and provides guidance on its use with different HTTP methods. This includes using `"targetSchema"` as a request description for PUT and PATCH. With draft-04, many users used `"schema"` to describe PUT and PATCH requests which is not needed.
47
+
Draft-06 clarifies this usage and provides guidance on its use with different HTTP methods. This includes using `"targetSchema"` as a request description for PUT and PATCH. With draft-04, many users used `"schema"` to describe PUT and PATCH requests which is not needed.
48
48
49
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.
50
50
51
-
### Q: What are key issues under consideraton for draft-07?
51
+
### Q: What are key issues under consideration for draft-07?
52
52
53
53
There are a number of relatively concrete proposals, although it is unlikely that all will be resolved in draft-07
54
54
@@ -112,6 +112,6 @@ A: Pick a proposal such as [`"allow"`](https://github.com/json-schema-org/json-s
112
112
113
113
### Q: If `"targetSchema"` is not the response, how do I describe responses?
114
114
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.
115
+
A: You should have hyper-schemas for your various success and error responses, but connecting them to links 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.
116
116
117
-
There has never been a Hyper-Schema keyword to explicitly associate responses with operations such as HTTP methods. The use cases for this seem to be about generating API documentation, so this is most likely a candidate for a [JSON Schema API Documentation vocabluary](https://github.com/json-schema-org/json-schema-spec/issues/136).
117
+
There has never been a Hyper-Schema keyword to explicitly associate responses with operations such as HTTP methods. The use cases for this seem to be about generating API documentation, so this is most likely a candidate for a [JSON Schema API Documentation vocabulary](https://github.com/json-schema-org/json-schema-spec/issues/136).
Copy file name to clipboardExpand all lines: draft-06/json-schema-migration-faq.md
+6-6
Original file line number
Diff line number
Diff line change
@@ -42,15 +42,15 @@ While not technically a change, the behavior of the `"uri"` format was not clear
42
42
43
43
When a relative path, fragment, or any other style of URI Reference (per RFC 3986) is allowable, use `"uri-reference"`.
44
44
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.
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 disabled by default for strict conformance.
46
46
47
47
### Q: What happened to draft-05?
48
48
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".
49
+
The draft-05 core and validation specifications were intended to be more clear and readable rewrites of draft-04, to give us a strong base for draft-06 changes. Implementors should **not** implement or advertise support for "draft-05".
50
50
51
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.
52
52
53
-
### Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`?
53
+
### Q: What happened to all the discussions around re-using schemas with `"additionalProperties"`?
54
54
55
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.
56
56
@@ -80,7 +80,7 @@ The difficulty is that if you attempt to do this:
80
80
}
81
81
```
82
82
83
-
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.
83
+
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.
84
84
85
85
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.
86
86
@@ -122,9 +122,9 @@ This will allow an object with either "foo" or "bar" or both, but will fail vali
122
122
123
123
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.
124
124
125
-
_*TODO:* Link to all of the discussions about other use cases and proposed solutions._
125
+
_*TODO:* Link to all the discussions about other use cases and proposed solutions._
126
126
127
-
### Q: What are key issues under consideraton for draft-07?
127
+
### Q: What are key issues under consideration for draft-07?
128
128
129
129
We are just starting to consider what to prioritize for the next draft.
0 commit comments