From d0cde384bf7e5ea70a625c4e35ed8dbf6fc5ceea Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 3 Apr 2017 16:30:15 -0700 Subject: [PATCH 01/11] Created FAQ: draft-wright-json-schema-hyperschema-01 (markdown) --- ...draft-wright-json-schema-hyperschema-01.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 FAQ:-draft-wright-json-schema-hyperschema-01.md diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md new file mode 100644 index 00000000..30e51b52 --- /dev/null +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -0,0 +1,138 @@ +* [**Q: What are the incompatible changes between draft-04 and draft-06?**](#changes) +* [**Q: What are key issues under consideraton for draft-07?**](#consideration) +* [**Q: Why were several major changes made to Hyper-Schema just before publication?**](#publication) +* [**Q: Why doesn't the spec mention or behave like HTML anymore?**](#html) +* [**Q: So how do I indicate which HTTP methods are supported on a link?**](#implicit) +* [**Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link?**](#explicit) +* [**Q: If `"targetSchema"` is not the response, how do I describe responses?**](#response) + +## _A note on draft naming and numbering:_ + +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: + +Hyper-Schema IETF Draft | Hyper-Schema Meta-Schema URI +---- | ---- +[draft-zyp-json-schema-00](https://tools.ietf.org/html/draft-zyp-json-schema-00) | [http://json-schema.org/draft-00/hyper-schema#](http://json-schema.org/draft-00/hyper-schema#) +[draft-zyp-json-schema-01](https://tools.ietf.org/html/draft-zyp-json-schema-01) | [http://json-schema.org/draft-01/hyper-schema#](http://json-schema.org/draft-01/hyper-schema#) +[draft-zyp-json-schema-02](https://tools.ietf.org/html/draft-zyp-json-schema-02) | [http://json-schema.org/draft-02/hyper-schema#](http://json-schema.org/draft-02/hyper-schema#) +[draft-zyp-json-schema-03](https://tools.ietf.org/html/draft-zyp-json-schema-03) | [http://json-schema.org/draft-03/hyper-schema#](http://json-schema.org/draft-03/hyper-schema#) +[draft-luff-json-hyper-schema-00](https://tools.ietf.org/html/draft-luff-json-hyper-schema-00) | [http://json-schema.org/draft-04/hyper-schema#](http://json-schema.org/draft-04/hyper-schema#) +[draft-wright-json-schema-hyperschema-00](https://tools.ietf.org/html/draft-wright-json-schema-hyperschema-00) | draft-05; [not published](https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links) +[draft-wright-json-schema-hyperschema-01](https://tools.ietf.org/html/draft-wright-json-schema-hyperschema-01) | [http://json-schema.org/draft-06/hyper-schema#](http://json-schema.org/draft-06/hyper-schema#) + +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. + +## Questions and Answers + + +### Q: What are the incompatible changes between draft-04 and draft-06? + +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. + +You will notice that some things are still in flight and under discussion for draft-07. We feel that draft-06 is a good set of changes for collecting feedback, with the most notable compatibility gaps easily addressed as extension keywords in the meantime. + +#### Changes from draft-04 to draft-05 + +keyword | change | consequence +---- | ---- | ---- +`"base"` | replaces looking up the nearest "self" link to determine the base URI for `"href"` | if you were relying on "self" links to change the base, set `"base"` explicitly +`"rel"` | "full" relation removed | use ["item"](https://github.com/json-schema-org/json-schema-spec/issues/295) +`"rel"` | "instances" and "create" relations removed | use ["collection"](https://github.com/json-schema-org/json-schema-spec/issues/295) +`"rel"` | "root" relation removed | use a fragment in your `"href"` URI Template +`"fragmentResolution"` | *removed* | media type determines how fragments are interpreted +`"pathStart"` | *removed* | *[no replacement]* +`"method"` | [changed back to HTML form semantics](https://tools.ietf.org/html/draft-zyp-json-schema-03#section-6.1.1.4.1) of "get" and "post" rather than all HTTP methods | *[changed again in draft-06 due to feedback that this was confusing]* + +#### Changes from draft-05 to draft-06 + +keyword | change | consequence +---- | ---- | ---- +`"method"` | *removed* | for HTTP method proposals, see issues [#73](https://github.com/json-schema-org/json-schema-spec/issues/73) and [#296](https://github.com/json-schema-org/json-schema-spec/issues/296) (use either `"method"` or `"allow"` as an extension keyword if needed); indication of how to use `"schema"` and `"encType"` no longer necessary +`"schema"` | *removed* | use `"hrefSchema"`, `"submissionSchema"`, or `"targetSchema"` | +`"encType"` | *removed* | use `"submissionEncType"` for request bodies; no longer needed for URI query strings +`"hrefSchema"` | *added* | replaces `"method": "get", "schema": {...}`, with additional functionality | +`"submissionSchema"` | *added* | replaces `"method": "post", "schema": {...}` +`"submissionEncType"` | *added* | replaces `"method": "post", "encType": "..."` +`"href"` | preprocessing removed | *to be replaced and expanded in future drafts* + +#### Proper use of `"targetSchema"` + +While `"targetSchema"` did not change its meaning in either recent draft, it has been widely misinterpreted. So it may feel like a change to use it as specified. + +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. + +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. + +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. + + +### Q: What are key issues under consideraton for draft-07? + +There are a number of relatively concrete proposals, although it is unlikely that all will be resolved in draft-07 + +* [#73](https://github.com/json-schema-org/json-schema-spec/issues/73) `"allow"` for HTTP method hints, proposed as its own keyword +* [#296](https://github.com/json-schema-org/json-schema-spec/issues/296) `"usageHints"` for general protocol usage hints, including HTTP "Allow" and "Accept-Patch" +* [#295](https://github.com/json-schema-org/json-schema-spec/issues/295) clarifying usage of "collection" and "item" in `application/schema+json` +* [#140](https://github.com/json-schema-org/json-schema-spec/issues/140) `"anchor"` and `"anchorPointer"` for adjusting the link's context URI +* [#74](https://github.com/json-schema-org/json-schema-spec/issues/74) `"deprecation"` property +* [#51](https://github.com/json-schema-org/json-schema-spec/issues/51) `"$data"`, particularly for use with `"const"` and/or `"default"` in `"hrefSchema"` and `"submissionSchema"` +* [#204](https://github.com/json-schema-org/json-schema-spec/issues/204) includes specific possible uses of `"default"` related to Hyper-Schema + +There are some important philosophical discussions about the scope and goals of Hyper-Schema, which hopefully will be resolved to help us make the right decisions for draft-07 and beyond: + +* [#294](https://github.com/json-schema-org/json-schema-spec/issues/294) how analogous Hyper-Schema should or shouldn't be to HTML, particularly in regard to forms vs anchor semantics +* [#288](https://github.com/json-schema-org/json-schema-spec/issues/288) whether link URI Templates must be resolvable without knowing whether input data will be used +* [#226](https://github.com/json-schema-org/json-schema-spec/issues/226) whether and how to handle APIs that do not strictly conform to HTTP semantics + + +Additionally, there are two further proposals for JSON Schema vocabularies which could impact or complement Hyper-Schema: + +* [Documentation](https://github.com/json-schema-org/json-schema-spec/issues/136), which could take over some static API description work +* [UI](https://github.com/json-schema-org/json-schema-spec/issues/67), which would deal with presentation issues for forms + + +### Q: Why were several major changes made to Hyper-Schema just before publication? + +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. + + +### Q: Why doesn't the spec mention or behave like HTML anymore? + +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: + +1. The change between draft-03 and draft-04 to let `"method"` indicate any HTTP method instead of HTML's `
` "get" and "post" values broke the original analogy to HTML +2. Only being able to use `"schema"` and `"encType"` for the request or the URI query string (but no other part of the URI) was overly restrictive for API design + +#### Splitting `"schema"` + +Instead of having `"schema"` perform two different things depending on `"method"`, we split it into two keywords, one for each use. This allows using both simultaneously when needed, which is a use case not present in HTML forms. + +`"hrefSchema"` replaces the `"method": "get"` use, but leverages URI Template variables so that client data-driven dynamic URIs are no longer limited to the query string. `"encType"` is no longer needed with this approach. + +`"submissionSchema"` directly replaces the `"method": "post"` use, with `"submissionEncType"` replacing `"encType"`. + +#### Removing `"method"` + +Draft-05 tried to restore the draft-03 behavior of `"method"`, but feedback told us that users found the change very confusing. With `"schema"` split, the draft-05 behavior of `"method"` was no longer needed. + +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. + + + +### Q: So how do I indicate which HTTP methods are supported on a link? + +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. + +Several URI schemes and namespaces, such as the [UUID namespace in the `urn:` scheme](https://tools.ietf.org/html/rfc4122), or the [`tag:` scheme](https://tools.ietf.org/html/rfc4151), are particularly suitable for creating unique identifiers. + + +### Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link? + +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. + + +### Q: If `"targetSchema"` is not the response, how do I describe responses? + +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. + +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). \ No newline at end of file From 13ef6b770fa4cf00d7605189af59c94365f97952 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 3 Apr 2017 16:33:23 -0700 Subject: [PATCH 02/11] Updated FAQ: draft wright json schema hyperschema 01 (markdown) --- FAQ:-draft-wright-json-schema-hyperschema-01.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md index 30e51b52..ee9e7a0a 100644 --- a/FAQ:-draft-wright-json-schema-hyperschema-01.md +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -1,3 +1,7 @@ +***THIS IS A DRAFT!*** For feedback, please comment on issue [#299](https://github.com/json-schema-org/json-schema-spec/issues/299) + +This will probably go on json-schema.org once approved. + * [**Q: What are the incompatible changes between draft-04 and draft-06?**](#changes) * [**Q: What are key issues under consideraton for draft-07?**](#consideration) * [**Q: Why were several major changes made to Hyper-Schema just before publication?**](#publication) From c7f1a5b6f2baf09c2f5331c703f14c0fa08f96d0 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 3 Apr 2017 21:08:20 -0700 Subject: [PATCH 03/11] Updated FAQ: draft wright json schema hyperschema 01 (markdown) --- FAQ:-draft-wright-json-schema-hyperschema-01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md index ee9e7a0a..b071c3db 100644 --- a/FAQ:-draft-wright-json-schema-hyperschema-01.md +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -105,7 +105,7 @@ A: During final review, it became apparent that there was no consensus on how to 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: 1. The change between draft-03 and draft-04 to let `"method"` indicate any HTTP method instead of HTML's `` "get" and "post" values broke the original analogy to HTML -2. Only being able to use `"schema"` and `"encType"` for the request or the URI query string (but no other part of the URI) was overly restrictive for API design +2. Only being able to use `"schema"` and `"encType"` for either the URI query string (but no other part of the URI) was or the request body, but not having any way to work with both, was overly restrictive for API design #### Splitting `"schema"` From dae18d3be0b5a8dbb97a37d6e94a885897daa438 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 3 Apr 2017 23:15:13 -0700 Subject: [PATCH 04/11] Updated FAQ: draft wright json schema hyperschema 01 (markdown) --- FAQ:-draft-wright-json-schema-hyperschema-01.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md index b071c3db..23b0fc06 100644 --- a/FAQ:-draft-wright-json-schema-hyperschema-01.md +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -104,8 +104,8 @@ A: During final review, it became apparent that there was no consensus on how to 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: -1. The change between draft-03 and draft-04 to let `"method"` indicate any HTTP method instead of HTML's `` "get" and "post" values broke the original analogy to HTML -2. Only being able to use `"schema"` and `"encType"` for either the URI query string (but no other part of the URI) was or the request body, but not having any way to work with both, was overly restrictive for API design +1. The change between draft-03 and draft-04 to let `"method"` indicate any HTTP method instead of HTML's `` "get" and "post" values broke the original analogy to HTML, and trying to change it back was not well-received +2. Only being able to use `"schema"` and `"encType"` for either the URI query string (but no other part of the URI) or the request body, but not having any way to work with both at once, was overly restrictive for API design #### Splitting `"schema"` From 3d8c94cf18326725c8e5bad230f1e2114ac7d5d4 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 17 Apr 2017 09:47:09 -0700 Subject: [PATCH 05/11] Updated FAQ: draft wright json schema hyperschema 01 (markdown) --- FAQ:-draft-wright-json-schema-hyperschema-01.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md index 23b0fc06..b66371aa 100644 --- a/FAQ:-draft-wright-json-schema-hyperschema-01.md +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -1,3 +1,5 @@ +## FAQ for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06) + ***THIS IS A DRAFT!*** For feedback, please comment on issue [#299](https://github.com/json-schema-org/json-schema-spec/issues/299) This will probably go on json-schema.org once approved. From 018d111f118fe547c0753b7fb9ed1240f8a4af2c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 17 Apr 2017 09:48:58 -0700 Subject: [PATCH 06/11] Updated FAQ: draft wright json schema hyperschema 01 (markdown) --- FAQ:-draft-wright-json-schema-hyperschema-01.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md index b66371aa..c804efc7 100644 --- a/FAQ:-draft-wright-json-schema-hyperschema-01.md +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -131,6 +131,8 @@ A: Ideally, this is implicitly conveyed by your link relation type, which is the Several URI schemes and namespaces, such as the [UUID namespace in the `urn:` scheme](https://tools.ietf.org/html/rfc4122), or the [`tag:` scheme](https://tools.ietf.org/html/rfc4151), are particularly suitable for creating unique identifiers. +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. + ### Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link? From 18d4ee97adfce6a5eddfb05c8d9ada8484884413 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 17 Apr 2017 09:50:29 -0700 Subject: [PATCH 07/11] Updated FAQ: draft wright json schema hyperschema 01 (markdown) --- FAQ:-draft-wright-json-schema-hyperschema-01.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/FAQ:-draft-wright-json-schema-hyperschema-01.md index c804efc7..5745f70c 100644 --- a/FAQ:-draft-wright-json-schema-hyperschema-01.md +++ b/FAQ:-draft-wright-json-schema-hyperschema-01.md @@ -1,9 +1,5 @@ ## FAQ for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06) -***THIS IS A DRAFT!*** For feedback, please comment on issue [#299](https://github.com/json-schema-org/json-schema-spec/issues/299) - -This will probably go on json-schema.org once approved. - * [**Q: What are the incompatible changes between draft-04 and draft-06?**](#changes) * [**Q: What are key issues under consideraton for draft-07?**](#consideration) * [**Q: Why were several major changes made to Hyper-Schema just before publication?**](#publication) From 190d0bedc3e0ef6accf2f8417ee92c0af93c40f9 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 7 May 2017 17:10:15 -0700 Subject: [PATCH 08/11] Created FAQ: draft-wright-json-schema[-validation]-01 (markdown) --- ...raft-wright-json-schema[-validation]-01.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 FAQ:-draft-wright-json-schema[-validation]-01.md diff --git a/FAQ:-draft-wright-json-schema[-validation]-01.md b/FAQ:-draft-wright-json-schema[-validation]-01.md new file mode 100644 index 00000000..9c9f1274 --- /dev/null +++ b/FAQ:-draft-wright-json-schema[-validation]-01.md @@ -0,0 +1,151 @@ +## FAQ for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06) + +* [**Q: What are the changes between draft-04 and draft-06?**](#changes) +* [**Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`?](#addlprop) +* [**Q: What are key issues under consideraton for draft-07?**](#consideration) + +## _A note on draft naming and numbering:_ + +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: + +Core/Validation IETF Drafts | Meta-Schema URI +---- | ---- +[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#) +[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#) +[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#) +[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#) +[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#) +[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) +[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#) + +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. + +## Questions and Answers + + +### Q: What are the changes between draft-04 and draft-06? + +#### Backwards-incompatible changes + +keyword | change | consequence +---- | ---- | ---- +`"id"` | replaced by `"$id"` | no longer easily confused with instance properties named `"id"` +`"$id"` | replaces `"id"` | behavior is identical, `$` prefix matches the other two core keywords +`"$ref"` | only allowed where a schema is expected | it is now possible to describe instance properties named `"$ref"` +`"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 + +#### Additions and backwards-compatible changes + +keyword | change | consequence +---- | ---- | ---- +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 +`"propertyNames"` | added | takes a schema which validates the *names* of all properties rather than their values +`"contains"` | added | array keyword that passes validation if its schema validates at least one array item +`"const"` | added | more readible form of a one-element `"enum"` +`"required"` | allows an empty array | an empty array indicates that no properties are required +`"dependencies"` | allows an empty array for property dependencies | an empty array indicates that there are no dependencies for the given property +`"format": "uri-reference"` | added | allows relative URI references per RFC 3986; see the section below about `"uri"` as a format +`"format": "uri-template"` | added | indicates an RFC 6570 conforming URI Template value, as is used in JSON Hyper-Schema for `"href"` +`"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"` +`"examples"` | added | array of examples with no validation effect; the value of `"default"` is usable as an example without repeating it under this keyword + +#### Formats: `"uri"` vs `"uri-reference"` + +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). + +`"uri"` should only be used when an absolute URI (starting with a scheme) is required. + +When a relative path, fragment, or any other style of URI Reference (per RFC 3986) is allowable, use `"uri-reference"`. + +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. + + +### Q: What happened to draft-05? + +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". + +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. + + +### Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`? + +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. + +The difficulty is that if you attempt to do this: + +```JSON +{ + "type": "object", + "allOf": [ + {"$ref": "#/definitions/foo"}, + {"$ref": "#/definitions/bar"} + ], + "definitions": { + "foo": { + "properties": { + "foo": {"type": "string"} + }, + "additionalProperties": false + }, + "bar": { + "properties": { + "bar": {"type": "number"} + }, + "additionalProperties": false + } + } +} +``` + +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. + +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. + +A workaround is available with the new `"propertyNames"` keyword: + +```JSON +{ + "type": "object", + "allOf": [ + {"$ref": "#/definitions/foo"}, + {"$ref": "#/definitions/bar"} + ], + "anyOf": [ + {"$ref": "#/definitions/fooNames"}, + {"$ref": "#/definitions/barNames"} + ], + "definitions": { + "foo": { + "properties": { + "foo": {"type": "string"} + } + }, + "fooNames": { + "propertyNames": {"enum": ["foo"]} + }, + "bar": { + "properties": { + "bar": {"type": "number"} + } + }, + "barNames": { + "propertyNames": {"enum": ["bar"]} + } + } +} +``` + +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. + +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. + +_*TODO:* Link to all of the discussions about other use cases and proposed solutions._ + + +### Q: What are key issues under consideraton for draft-07? + +We are just starting to consider what to prioritize for the next draft. + +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. + +For validation, there are a number of competing proposals. We will update this document as we get agreement on priorities. From f6fa7a86d5e618ce97f62a44ecff5190039ed7f3 Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Thu, 8 Jun 2017 14:45:00 -0500 Subject: [PATCH 09/11] Move FAQs to Jekyll friendly name and location --- .../json-hyper-schema-migration-faq.md | 0 .../json-schema-migration-faq.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename FAQ:-draft-wright-json-schema-hyperschema-01.md => draft-06/json-hyper-schema-migration-faq.md (100%) rename FAQ:-draft-wright-json-schema[-validation]-01.md => draft-06/json-schema-migration-faq.md (100%) diff --git a/FAQ:-draft-wright-json-schema-hyperschema-01.md b/draft-06/json-hyper-schema-migration-faq.md similarity index 100% rename from FAQ:-draft-wright-json-schema-hyperschema-01.md rename to draft-06/json-hyper-schema-migration-faq.md diff --git a/FAQ:-draft-wright-json-schema[-validation]-01.md b/draft-06/json-schema-migration-faq.md similarity index 100% rename from FAQ:-draft-wright-json-schema[-validation]-01.md rename to draft-06/json-schema-migration-faq.md From 6a81804a56a37dbdde1af8773ff327a8dff875d3 Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Thu, 8 Jun 2017 15:17:14 -0500 Subject: [PATCH 10/11] Add Draft 6 migration FAQs to website --- documentation.md | 4 ++- draft-05/README.md | 4 +++ draft-06/README.md | 37 +++++++++++++++++++ draft-06/json-hyper-schema-migration-faq.md | 39 ++++----------------- draft-06/json-schema-migration-faq.md | 36 +++++-------------- 5 files changed, 60 insertions(+), 60 deletions(-) create mode 100644 draft-06/README.md diff --git a/documentation.md b/documentation.md index df821f73..2c3c137c 100644 --- a/documentation.md +++ b/documentation.md @@ -3,7 +3,9 @@ layout: page title: Specification --- -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: +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. + +The specification is split into three parts, Core, Validation, and Hyper-Schema: |--------------------------------------------------------------|-------------------------------------------------| | [JSON Schema Core](latest/json-schema-core.html) | defines the basic foundation of JSON Schema | diff --git a/draft-05/README.md b/draft-05/README.md index 7a34cb9d..82507210 100644 --- a/draft-05/README.md +++ b/draft-05/README.md @@ -1,3 +1,7 @@ +--- +layout: default +--- + ## Explanation for lack of draft-05 meta-schemas "Draft-05" in the sequential meta-schema numbering would have diff --git a/draft-06/README.md b/draft-06/README.md new file mode 100644 index 00000000..047d9c8a --- /dev/null +++ b/draft-06/README.md @@ -0,0 +1,37 @@ +--- +layout: default +--- + +# Draft 6 Release Notes + +- [JSON Schema Release FAQ](json-schema-migration-faq.md) +- [JSON Hyper-Schema Release FAQ](json-hyper-schema-migration-faq.md) +- **A note on draft naming and numbering:** + + + 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. + + For JSON Schema, the correspondences are: + + Core/Validation IETF Drafts | Meta-Schema URI + ---- | ---- + [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) + [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) + [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) + [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) + [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) + [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) + [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) + + + For JSON Hyper-Schema, the correspondences are: + + Hyper-Schema IETF Draft | Hyper-Schema Meta-Schema URI + ---- | ---- + [draft-zyp-json-schema-00](https://tools.ietf.org/html/draft-zyp-json-schema-00) | [http://json-schema.org/draft-00/hyper-schema](http://json-schema.org/draft-00/hyper-schema) + [draft-zyp-json-schema-01](https://tools.ietf.org/html/draft-zyp-json-schema-01) | [http://json-schema.org/draft-01/hyper-schema](http://json-schema.org/draft-01/hyper-schema) + [draft-zyp-json-schema-02](https://tools.ietf.org/html/draft-zyp-json-schema-02) | [http://json-schema.org/draft-02/hyper-schema](http://json-schema.org/draft-02/hyper-schema) + [draft-zyp-json-schema-03](https://tools.ietf.org/html/draft-zyp-json-schema-03) | [http://json-schema.org/draft-03/hyper-schema](http://json-schema.org/draft-03/hyper-schema) + [draft-luff-json-hyper-schema-00](https://tools.ietf.org/html/draft-luff-json-hyper-schema-00) | [http://json-schema.org/draft-04/hyper-schema](http://json-schema.org/draft-04/hyper-schema) + [draft-wright-json-schema-hyperschema-00](https://tools.ietf.org/html/draft-wright-json-schema-hyperschema-00) | draft-05; [not published](../draft-05/README.md) + [draft-wright-json-schema-hyperschema-01](https://tools.ietf.org/html/draft-wright-json-schema-hyperschema-01) | [http://json-schema.org/draft-06/hyper-schema](http://json-schema.org/draft-06/hyper-schema) diff --git a/draft-06/json-hyper-schema-migration-faq.md b/draft-06/json-hyper-schema-migration-faq.md index 5745f70c..86536a91 100644 --- a/draft-06/json-hyper-schema-migration-faq.md +++ b/draft-06/json-hyper-schema-migration-faq.md @@ -1,32 +1,13 @@ -## FAQ for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06) +--- +title: JSON Hyper-Schema Draft 6 migration FAQ +layout: page +--- -* [**Q: What are the incompatible changes between draft-04 and draft-06?**](#changes) -* [**Q: What are key issues under consideraton for draft-07?**](#consideration) -* [**Q: Why were several major changes made to Hyper-Schema just before publication?**](#publication) -* [**Q: Why doesn't the spec mention or behave like HTML anymore?**](#html) -* [**Q: So how do I indicate which HTTP methods are supported on a link?**](#implicit) -* [**Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link?**](#explicit) -* [**Q: If `"targetSchema"` is not the response, how do I describe responses?**](#response) +FAQ for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06). -## _A note on draft naming and numbering:_ +* TOC +{:toc} -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: - -Hyper-Schema IETF Draft | Hyper-Schema Meta-Schema URI ----- | ---- -[draft-zyp-json-schema-00](https://tools.ietf.org/html/draft-zyp-json-schema-00) | [http://json-schema.org/draft-00/hyper-schema#](http://json-schema.org/draft-00/hyper-schema#) -[draft-zyp-json-schema-01](https://tools.ietf.org/html/draft-zyp-json-schema-01) | [http://json-schema.org/draft-01/hyper-schema#](http://json-schema.org/draft-01/hyper-schema#) -[draft-zyp-json-schema-02](https://tools.ietf.org/html/draft-zyp-json-schema-02) | [http://json-schema.org/draft-02/hyper-schema#](http://json-schema.org/draft-02/hyper-schema#) -[draft-zyp-json-schema-03](https://tools.ietf.org/html/draft-zyp-json-schema-03) | [http://json-schema.org/draft-03/hyper-schema#](http://json-schema.org/draft-03/hyper-schema#) -[draft-luff-json-hyper-schema-00](https://tools.ietf.org/html/draft-luff-json-hyper-schema-00) | [http://json-schema.org/draft-04/hyper-schema#](http://json-schema.org/draft-04/hyper-schema#) -[draft-wright-json-schema-hyperschema-00](https://tools.ietf.org/html/draft-wright-json-schema-hyperschema-00) | draft-05; [not published](https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links) -[draft-wright-json-schema-hyperschema-01](https://tools.ietf.org/html/draft-wright-json-schema-hyperschema-01) | [http://json-schema.org/draft-06/hyper-schema#](http://json-schema.org/draft-06/hyper-schema#) - -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. - -## Questions and Answers - - ### Q: What are the incompatible changes between draft-04 and draft-06? 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 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. - ### Q: What are key issues under consideraton for draft-07? 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 * [Documentation](https://github.com/json-schema-org/json-schema-spec/issues/136), which could take over some static API description work * [UI](https://github.com/json-schema-org/json-schema-spec/issues/67), which would deal with presentation issues for forms - ### Q: Why were several major changes made to Hyper-Schema just before publication? 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. - ### Q: Why doesn't the spec mention or behave like HTML anymore? 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 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. - ### Q: So how do I indicate which HTTP methods are supported on a link? 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 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. - ### Q: No, really. How do I _explicitly_ indicate which HTTP methods are supported on a link? 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. - ### Q: If `"targetSchema"` is not the response, how do I describe responses? 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. diff --git a/draft-06/json-schema-migration-faq.md b/draft-06/json-schema-migration-faq.md index 9c9f1274..8265e2db 100644 --- a/draft-06/json-schema-migration-faq.md +++ b/draft-06/json-schema-migration-faq.md @@ -1,28 +1,13 @@ -## FAQ for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06) +--- +title: JSON Schema Draft 6 migration FAQ +layout: page +--- -* [**Q: What are the changes between draft-04 and draft-06?**](#changes) -* [**Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`?](#addlprop) -* [**Q: What are key issues under consideraton for draft-07?**](#consideration) +FAQ for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06). -## _A note on draft naming and numbering:_ +* TOC +{:toc} -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: - -Core/Validation IETF Drafts | Meta-Schema URI ----- | ---- -[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#) -[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#) -[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#) -[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#) -[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#) -[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) -[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#) - -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. - -## Questions and Answers - - ### Q: What are the changes between draft-04 and draft-06? #### Backwards-incompatible changes @@ -59,21 +44,19 @@ When a relative path, fragment, or any other style of URI Reference (per RFC 398 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. - ### Q: What happened to draft-05? 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". 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. - ### Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`? 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. The difficulty is that if you attempt to do this: -```JSON +```json { "type": "object", "allOf": [ @@ -103,7 +86,7 @@ So in this example, if the instance has a "bar" property, it will fail the first A workaround is available with the new `"propertyNames"` keyword: -```JSON +```json { "type": "object", "allOf": [ @@ -141,7 +124,6 @@ It does require duplicating the names, and the awkward use of both an `"allOf"` _*TODO:* Link to all of the discussions about other use cases and proposed solutions._ - ### Q: What are key issues under consideraton for draft-07? We are just starting to consider what to prioritize for the next draft. From 3ae4682e8798929c77a3326903c52afba265a271 Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Thu, 8 Jun 2017 15:35:29 -0500 Subject: [PATCH 11/11] Correct some spelling/grammar mistakes --- draft-06/json-hyper-schema-migration-faq.md | 8 ++++---- draft-06/json-schema-migration-faq.md | 12 ++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/draft-06/json-hyper-schema-migration-faq.md b/draft-06/json-hyper-schema-migration-faq.md index 86536a91..1753a104 100644 --- a/draft-06/json-hyper-schema-migration-faq.md +++ b/draft-06/json-hyper-schema-migration-faq.md @@ -44,11 +44,11 @@ While `"targetSchema"` did not change its meaning in either recent draft, it has 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. -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. +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. 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. -### Q: What are key issues under consideraton for draft-07? +### Q: What are key issues under consideration for draft-07? There are a number of relatively concrete proposals, although it is unlikely that all will be resolved in draft-07 @@ -112,6 +112,6 @@ A: Pick a proposal such as [`"allow"`](https://github.com/json-schema-org/json-s ### Q: If `"targetSchema"` is not the response, how do I describe responses? -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. +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. -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). \ No newline at end of file +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). \ No newline at end of file diff --git a/draft-06/json-schema-migration-faq.md b/draft-06/json-schema-migration-faq.md index 8265e2db..2ad55e7b 100644 --- a/draft-06/json-schema-migration-faq.md +++ b/draft-06/json-schema-migration-faq.md @@ -42,15 +42,15 @@ While not technically a change, the behavior of the `"uri"` format was not clear When a relative path, fragment, or any other style of URI Reference (per RFC 3986) is allowable, use `"uri-reference"`. -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. +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. ### Q: What happened to draft-05? -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". +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". 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. -### Q: What happened to all of the discussions around re-using schemas with `"additionalProperties"`? +### Q: What happened to all the discussions around re-using schemas with `"additionalProperties"`? 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. @@ -80,7 +80,7 @@ The difficulty is that if you attempt to do this: } ``` -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. +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. 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. @@ -122,9 +122,9 @@ This will allow an object with either "foo" or "bar" or both, but will fail vali 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. -_*TODO:* Link to all of the discussions about other use cases and proposed solutions._ +_*TODO:* Link to all the discussions about other use cases and proposed solutions._ -### Q: What are key issues under consideraton for draft-07? +### Q: What are key issues under consideration for draft-07? We are just starting to consider what to prioritize for the next draft.