diff --git a/components/DocTable.tsx b/components/DocTable.tsx new file mode 100644 index 000000000..770a660ca --- /dev/null +++ b/components/DocTable.tsx @@ -0,0 +1,64 @@ +import React from 'react'; +import Link from 'next/link'; + +const DocTable = ({ frontmatter }: any) => { + return ( + <> +
+ + + + + + + + + + + + + + + + + + + +
+ Specification + + + {' '} + {frontmatter.Specification} + +
+ Published + + {frontmatter.Published} +
+ Authors + + {frontmatter.authors.map((author: string, index: number) => { + return
{author}
; + })} +
+ Metaschema + + + {frontmatter.Metaschema} + +
+
+ + ); +}; + +export default DocTable; diff --git a/components/Sidebar.tsx b/components/Sidebar.tsx index 16ad66826..6bac75bc8 100644 --- a/components/Sidebar.tsx +++ b/components/Sidebar.tsx @@ -133,15 +133,17 @@ const getReferencePath = [ '/implementers/interfaces', ]; const getSpecificationPath = [ - '/draft/2020-12/release-notes', - '/draft/2019-09/release-notes', - '/draft-07/json-schema-release-notes', - '/draft-06/json-schema-release-notes', - '/draft-05/readme', - '/draft-07/json-hyper-schema-release-notes', - '/draft-06/json-hyper-schema-release-notes', + '/draft/2020-12', + '/draft/2019-09', + '/draft-07', + '/draft-06', + '/draft-05', '/specification-links', + '/specification/migration', + '/specification/release-notes', + '/specification/json-hyper-schema', '/specification', + '/specification-links', ]; export const SidebarLayout = ({ children }: { children: React.ReactNode }) => { @@ -660,54 +662,39 @@ export const DocsNav = ({ id='specification' > + + +
+ + + + + + +
+ + - - + - -
- - - -
diff --git a/pages/draft-05/[slug].page.tsx b/pages/draft-05/[slug].page.tsx deleted file mode 100644 index 798581221..000000000 --- a/pages/draft-05/[slug].page.tsx +++ /dev/null @@ -1,38 +0,0 @@ -import React from 'react'; -import Head from 'next/head'; -import StyledMarkdown from '~/components/StyledMarkdown'; -import { getLayout } from '~/components/Sidebar'; -import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; -import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; -import { Headline1 } from '~/components/Headlines'; -import { SectionContext } from '~/context'; -import { DocsHelp } from '~/components/DocsHelp'; - -export async function getStaticPaths() { - return getStaticMarkdownPaths('pages/draft-05'); -} -export async function getStaticProps(args: any) { - return getStaticMarkdownProps(args, 'pages/draft-05'); -} - -export default function StaticMarkdownPage({ - frontmatter, - content, -}: { - frontmatter: any; - content: any; -}) { - const markdownFile = '_index'; - const newTitle = 'JSON Schema - ' + frontmatter.title; - return ( - - - {newTitle} - - {frontmatter.title} - - - - ); -} -StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft-05/index.md b/pages/draft-05/index.md new file mode 100644 index 000000000..91c72c2b0 --- /dev/null +++ b/pages/draft-05/index.md @@ -0,0 +1,16 @@ +--- +title: 'Draft-05' +Published: '13 October 2016' +type: docs +authors: ['Austin Wright'] +Metaschema: 'https://json-schema.org/draft-04/schema' +Specification: 'https://json-schema.org/draft-05/draft-wright-json-schema-00.pdf' +--- + +### Draft-05 Documents + +- Core: [draft-wright-json-schema-00](https://json-schema.org/draft-05/draft-wright-json-schema-00.pdf) ([changes](https://json-schema.org/draft-05/draft-wright-json-schema-00.pdf#appendix-B)) +- Validation: [draft-wright-json-schema-validation-00](https://json-schema.org/draft-05/draft-wright-json-schema-validation-00.pdf) ([changes](https://json-schema.org/draft-05/draft-wright-json-schema-validation-00.pdf#appendix-B)) +- Hyper-Schema: [draft-wright-json-schema-hyperschema-00](https://json-schema.org/draft-05/draft-wright-json-schema-hyperschema-00.pdf) ([changes](https://json-schema.org/draft-05/draft-wright-json-schema-hyperschema-00.pdf#appendix-B)) +- Draft 5 was primarily a cleanup of Draft 4 and continued to use the Draft 4 meta-schemas. +- Published: 13-October-2016 diff --git a/pages/draft-05/index.page.tsx b/pages/draft-05/index.page.tsx new file mode 100644 index 000000000..1d619e0b4 --- /dev/null +++ b/pages/draft-05/index.page.tsx @@ -0,0 +1,46 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { SectionContext } from '~/context'; +import DocTable from '~/components/DocTable'; +import { Headline1 } from '~/components/Headlines'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync('pages/draft-05/index.md', 'utf-8'); + const main = fs.readFileSync('pages/draft-05/release-notes.md', 'utf-8'); + const { content: indexContent, data: indexData } = matter(index); + const { content: bodyContent } = matter(main); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + body: bodyContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + + + + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/draft-05/readme.md b/pages/draft-05/release-notes.md similarity index 68% rename from pages/draft-05/readme.md rename to pages/draft-05/release-notes.md index d7289cc4c..cd6a96658 100644 --- a/pages/draft-05/readme.md +++ b/pages/draft-05/release-notes.md @@ -1,10 +1,7 @@ ---- -title: Explanation for lack of draft-05 meta-schemas -section: docs ---- +### Explanation for lack of draft-05 meta-schemas -“Draft-05” in the sequential meta-schema numbering would have referred to the draft-wright-jsonschema*-00 specifications. +“Draft-05” in the sequential meta-schema numbering would have referred to the draft-wright-jsonschema\*-00 specifications. These specifications were intended as modernized and tidied versions of the specifications referenced by the “Draft-04” meta-schemas, so those draft-04 meta-schemas should continue to be used. -“Draft-06” meta-schemas will be published for the next set of specifications. \ No newline at end of file +“Draft-06” meta-schemas will be published for the next set of specifications. diff --git a/pages/draft-06/[slug].page.tsx b/pages/draft-06/[slug].page.tsx deleted file mode 100644 index fc447db63..000000000 --- a/pages/draft-06/[slug].page.tsx +++ /dev/null @@ -1,39 +0,0 @@ -import React from 'react'; -import Head from 'next/head'; -import { getLayout } from '~/components/Sidebar'; -import StyledMarkdown from '~/components/StyledMarkdown'; -import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; -import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; -import { Headline1 } from '~/components/Headlines'; -import { SectionContext } from '~/context'; -import { DocsHelp } from '~/components/DocsHelp'; - -export async function getStaticPaths() { - return getStaticMarkdownPaths('pages/draft-06'); -} -export async function getStaticProps(args: any) { - return getStaticMarkdownProps(args, 'pages/draft-06'); -} - -export default function StaticMarkdownPage({ - frontmatter, - content, -}: { - frontmatter: any; - content: any; -}) { - const markdownFile = '_index'; - const newTitle = 'JSON Schema - ' + frontmatter.title; - - return ( - - - {newTitle} - - {frontmatter.title} - - - - ); -} -StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft-06/index.md b/pages/draft-06/index.md new file mode 100644 index 000000000..7532b5637 --- /dev/null +++ b/pages/draft-06/index.md @@ -0,0 +1,15 @@ +--- +title: 'Draft-06' +Published: '21 April 2017' +type: docs +authors: ['Austin Wright', 'Henry Andrews'] +Metaschema: 'https://json-schema.org/draft-06/schema' +Specification: 'https://json-schema.org/draft-06/draft-wright-json-schema-01.html' +--- + +### Draft-06 Documents + +- Validation: [draft-wright-json-schema-validation-01](https://json-scheclsma.org/draft-06/draft-wright-json-schema-validation-01.html) ([changes](https://json-schema.org/draft-06/draft-wright-json-schema-validation-01.html#rfc.appendix.B)) ([schema migration FAQ](https://json-schema.org/draft-06/json-schema-release-notes)) +- Hyper-Schema: [draft-wright-json-schema-hyperschema-01](https://json-schema.org/draft-06/draft-wright-json-schema-hyperschema-01.html) ([changes](https://json-schema.org/draft-06/draft-wright-json-schema-hyperschema-01.html#rfc.appendix.B)) ([hyper-schema migration FAQ](https://json-schema.org/draft-06/json-hyper-schema-release-notes)) +- [JSON Schema meta-schema](https://json-schema.org/draft-06/schema) +- [JSON Hyper-Schema meta-schema](https://json-schema.org/draft-06/hyper-schema) diff --git a/pages/draft-06/index.page.tsx b/pages/draft-06/index.page.tsx new file mode 100644 index 000000000..4e63230f1 --- /dev/null +++ b/pages/draft-06/index.page.tsx @@ -0,0 +1,61 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { SectionContext } from '~/context'; +import DocTable from '~/components/DocTable'; +import { Headline1 } from '~/components/Headlines'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync('pages/draft-06/index.md', 'utf-8'); + const main = fs.readFileSync( + 'pages/draft-06/json-schema-release-notes.md', + 'utf-8', + ); + const hyperSchema = fs.readFileSync( + 'pages/draft-06/json-hyper-schema-release-notes.md', + 'utf-8', + ); + const readme = fs.readFileSync('pages/draft-06/readme.md', 'utf-8'); + + const { content: indexContent, data: indexData } = matter(index); + const { content: bodyContent } = matter(main); + const { content: hyperSchemaContent } = matter(hyperSchema); + const { content: readmeContent } = matter(readme); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + body: bodyContent, + hyperSchema: hyperSchemaContent, + readme: readmeContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + + + + + + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/draft-06/json-hyper-schema-release-notes.md b/pages/draft-06/json-hyper-schema-release-notes.md index 19735c3a3..94ce73117 100644 --- a/pages/draft-06/json-hyper-schema-release-notes.md +++ b/pages/draft-06/json-hyper-schema-release-notes.md @@ -1,107 +1,102 @@ ---- -title: JSON Hyper-Schema Draft-06 Release Notes -section: docs ---- +### JSON Hyper-Schema Draft-06 Release Notes Release notes for migrating from draft-luff-json-hyper-schema-00 (draft-04) to draft-wright-json-schema-hyperschema-01 (draft-06).
NOTE: draft-07 has been released
-The [migration notes for draft-07](../draft-07/json-hyper-schema-release-notes) give a much more straightforward overview of migrating from draft-04 to draft-07 by skipping the complicated intermediate states of draft-05 and draft-06. This page has been retained for historical interest, but it is not recommened for those who just want to get going with the latest draft. +The [migration notes for draft-07](../draft-07/json-hyper-schema-release-notes) give a much more straightforward overview of migrating from draft-04 to draft-07 by skipping the complicated intermediate states of draft-05 and draft-06. This page has been retained for historical interest, but it is not recommened for those who only want to get going with the latest draft. -**For implementors:** We recommend just implementing draft-07, and not draft-06 or earlier. +**For implementors:** We recommend only implementing draft-07, and not draft-06 or earlier. -* [Q: What are the incompatible changes between draft-04 and draft-06?](#q:-what-are-the-incompatible-changes-between-draft-04-and-draft-06) - * [Changes from draft-04 to draft-05](#changes-from-draft-04-to-draft-05) - * [Changes from draft-05 to draft-06](#changes-from-draft-05-to-draft-06) - * [Proper use of "targetSchema"](#proper-use-of) -* [Q: Why were several major changes made to Hyper-Schema just before draft-06’s publication?](#q:-why-were-several-major-changes-made-to-hyper-schema-just-before-draft-06's-publication) -* [Q: Why doesn’t the spec mention or behave like HTML anymore?](#q:-why-doesn't-the-spec-mention-or-behave-like-html-anymore) - * [Splitting "schema"](#splitting) - * [Removing "method"](#removing) -* [Q: So how do I indicate which HTTP methods are supported on a link?](#q:-so-how-do-i-indicate-which-http-methods-are-supported-on-a-link) -* [Q: No, really. How do I explicitly indicate which HTTP methods are supported on a link?](#q:-no-really.-how-do-i-indicate-which-http-methods-are-supported-on-a-link) -* [Q: If "targetSchema" is not the response, how do I describe responses?](#q:-if-is-not-the-response-how-do-i-describe-responses) +- [Q: What are the incompatible changes between draft-04 and draft-06?](#q:-what-are-the-incompatible-changes-between-draft-04-and-draft-06) + - [Changes from draft-04 to draft-05](#changes-from-draft-04-to-draft-05) + - [Changes from draft-05 to draft-06](#changes-from-draft-05-to-draft-06) + - [Proper use of "targetSchema"](#proper-use-of) +- [Q: Why were several major changes made to Hyper-Schema before draft-06’s publication?](#q:-why-were-several-major-changes-made-to-hyper-schema-just-before-draft-06's-publication) +- [Q: Why doesn’t the spec mention or behave like HTML anymore?](#q:-why-doesn't-the-spec-mention-or-behave-like-html-anymore) + - [Splitting "schema"](#splitting) + - [Removing "method"](#removing) +- [Q: So how do I indicate which HTTP methods are supported on a link?](#q:-so-how-do-i-indicate-which-http-methods-are-supported-on-a-link) +- [Q: No, really. How do I explicitly indicate which HTTP methods are supported on a link?](#q:-no-really.-how-do-i-indicate-which-http-methods-are-supported-on-a-link) +- [Q: If "targetSchema" is not the response, how do I describe responses?](#q:-if-is-not-the-response-how-do-i-describe-responses) -### Q: What are the incompatible changes between draft-04 and draft-06? +#### 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. -While we knew that there were still major gaps in draft-06, we felt that it was a good set of changes for collecting feedback. With draft-07 published, that draft or later should be used, and draft-06 becomes an historical curiosity. +While we knew that there were still major gaps in draft-06, we felt that it was a good set of changes for collecting feedback. With draft-07 published, that draft or later should be used, and draft-06 becomes an historical curiosity. -#### Changes from draft-04 to draft-05 +##### 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](../draft-03/draft-zyp-json-schema-03.pdf) of "get" and "post" rather than all HTTP methods | *[changed again in draft-06 due to feedback that this was confusing]* +| 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](../draft-03/draft-zyp-json-schema-03.pdf) 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 +##### 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* +| 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"` +##### 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. +Although 'targetSchema' has kept its meaning, its interpretation has varied. Therefore, using it as intended might feel like a modification -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. +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 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. +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, the [`"targetHints"` proposal](https://github.com/json-schema-org/json-schema-spec/issues/296) has been accepted into draft-07. Among other things, it enables hinting at "Accept-Patch", which is needed to properly use `"targetSchema"` with HTTP PATCH. There will be examples and detailed guidance in draft-07. +However, the [`"targetHints"` proposal](https://github.com/json-schema-org/json-schema-spec/issues/296) has been accepted into draft-07. Among other things, it enables hinting at "Accept-Patch", which is needed to properly use `"targetSchema"` with HTTP PATCH. There will be examples and detailed guidance in draft-07. -### Q: Why were several major changes made to Hyper-Schema just before draft-06's publication? +#### Q: Why were several major changes made to Hyper-Schema just before draft-06's 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. +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? +#### Q: Why doesn't the spec mention or behave like HTML anymore? A: 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, 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"` +##### 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. +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. +`"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"` +##### 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. +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. +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? +#### 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. +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. 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? +If you need to explicitly indicate which HTTP methods are supported, you can use 'targetHints' from draft-07 as an extension to draft-06. -A: The [`"targetHints"` proposal](https://github.com/json-schema-org/json-schema-spec/issues/296) is part of draft-07, so using it as an extension to draft-06 is an option, but we recommend simply using draft-07 at this point. - -### Q: If `"targetSchema"` is not the response, how do I describe responses? +#### 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 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 vocabulary](https://github.com/json-schema-org/json-schema-vocabularies/issues/1). +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-vocabularies/issues/1). diff --git a/pages/draft-06/json-schema-release-notes.md b/pages/draft-06/json-schema-release-notes.md index d7632ed23..f450c9aff 100644 --- a/pages/draft-06/json-schema-release-notes.md +++ b/pages/draft-06/json-schema-release-notes.md @@ -1,7 +1,4 @@ ---- -title: Draft-06 Release Notes -section: docs ---- +### Draft-06 release notes Release notes for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draft-06). @@ -10,41 +7,41 @@ Release notes for migrating from zyp-04 and fge-00 (draft-04) to wright-01 (draf Note that draft-07 core and validation are backwards-compatible with draft-06. For more information, see that draft's [migration notes](../../draft-07/json-schema-release-notes). -* [Q: What are the changes between draft-04 and draft-06?](#q:-what-are-the-changes-between-draft-04-and-draft-06) - * [Backwards-incompatible changes](#backwards-incompatible-changes) - * [Additions and backwards-compatible changes](#additions-and-backwards-compatible-changes) - * [Formats: "uri" vs "uri-reference"](#formats:-vs) -* [Q: What happened to draft-05?](#q:-what-happened-to-draft-05) -* [Q: What happened to all the discussions around re-using schemas with "additionalProperties"?](#q:-what-happened-to-all-the-discussions-around-re-using-schemas-with-additionalproperties) - -### 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 -`"type"` | definition of `"integer"` | in draft-04, `"integer"` is listed as a primitive type and defined as "a JSON number without a fraction or exponent part"; in draft-06, `"integer"` is not considered a primitive type and is only defined in the section for keyword `"type"` as "any number with a zero fractional part"; `1.0` is thus not a valid `"integer"` type in draft-04 and earlier, but is a valid `"integer"` type in draft-06 and later; note that both drafts say that integers SHOULD be encoded in JSON without fractional parts - -#### 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"` +- [Q: What are the changes between draft-04 and draft-06?](#q:-what-are-the-changes-between-draft-04-and-draft-06) + - [Backwards-incompatible changes](#backwards-incompatible-changes) + - [Additions and backwards-compatible changes](#additions-and-backwards-compatible-changes) + - [Formats: "uri" vs "uri-reference"](#formats:-vs) +- [Q: What happened to draft-05?](#q:-what-happened-to-draft-05) +- [Q: What happened to all the discussions around re-using schemas with "additionalProperties"?](#q:-what-happened-to-all-the-discussions-around-re-using-schemas-with-additionalproperties) + +#### 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 | +| `"type"` | definition of `"integer"` | in draft-04, `"integer"` is listed as a primitive type and defined as "a JSON number without a fraction or exponent part"; in draft-06, `"integer"` is not considered a primitive type and is only defined in the section for keyword `"type"` as "any number with a zero fractional part"; `1.0` is thus not a valid `"integer"` type in draft-04 and earlier, but is a valid `"integer"` type in draft-06 and later; note that both drafts say that integers SHOULD be encoded in JSON without fractional parts | + +##### 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). @@ -54,80 +51,74 @@ 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 disabled by default for strict conformance. -### Q: What happened to draft-05? +#### Q: What happened to 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". +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 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. +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. -[All of the proposals in this area](https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aissue+is%3Aopen+label%3A%22re-use+%2F+addlProps%22) will be the focus of [draft-08](https://github.com/json-schema-org/json-schema-spec/milestone/6). While we made progress in eliminating some options during draft-07, the remaining divisions are deep enough to warrant making it the primary focus of a draft ([draft-07](https://github.com/json-schema-org/json-schema-spec/milestone/5)'s primary focus is Hyper-Schema). +[All of the proposals in this area](https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aissue+is%3Aopen+label%3A%22re-use+%2F+addlProps%22) will be the focus of [draft-08](https://github.com/json-schema-org/json-schema-spec/milestone/6). While we made progress in eliminating some options during draft-07, the remaining divisions are deep enough to warrant making it the primary focus of a draft ([draft-07](https://github.com/json-schema-org/json-schema-spec/milestone/5)'s primary focus is Hyper-Schema). 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 - } + "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. +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. +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" } - ], - "propertyNames": { - "anyOf": [ - { "$ref": "#/definitions/fooNames" }, - { "$ref": "#/definitions/barNames" } - ] + "type": "object", + "allOf": [{ "$ref": "#/definitions/foo" }, { "$ref": "#/definitions/bar" }], + "propertyNames": { + "anyOf": [ + { "$ref": "#/definitions/fooNames" }, + { "$ref": "#/definitions/barNames" } + ] + }, + "definitions": { + "foo": { + "properties": { + "foo": { "type": "string" } + } }, - "definitions": { - "foo": { - "properties": { - "foo": { "type": "string" } - } - }, - "fooNames": { "enum": ["foo"] }, - "bar": { - "properties": { - "bar": { "type": "number" } - } - }, - "barNames": { "enum": ["bar"] } - } + "fooNames": { "enum": ["foo"] }, + "bar": { + "properties": { + "bar": { "type": "number" } + } + }, + "barNames": { "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. +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. diff --git a/pages/draft-06/readme.md b/pages/draft-06/readme.md index cbef1dbb0..3a7c309b7 100644 --- a/pages/draft-06/readme.md +++ b/pages/draft-06/readme.md @@ -1,7 +1,2 @@ ---- -title: Draft-06 Release Notes -section: docs ---- - - [JSON Schema Release Notes](/draft-06/json-schema-release-notes) -- [JSON Hyper-Schema Release Notes](/draft-06/json-hyper-schema-release-notes) \ No newline at end of file +- [JSON Hyper-Schema Release Notes](/draft-06/json-hyper-schema-release-notes) diff --git a/pages/draft-07/[slug].page.tsx b/pages/draft-07/[slug].page.tsx deleted file mode 100644 index be10dfdba..000000000 --- a/pages/draft-07/[slug].page.tsx +++ /dev/null @@ -1,39 +0,0 @@ -import React from 'react'; -import Head from 'next/head'; -import StyledMarkdown from '~/components/StyledMarkdown'; -import { getLayout } from '~/components/Sidebar'; -import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; -import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; -import { Headline1 } from '~/components/Headlines'; -import { SectionContext } from '~/context'; -import { DocsHelp } from '~/components/DocsHelp'; - -export async function getStaticPaths() { - return getStaticMarkdownPaths('pages/draft-07'); -} -export async function getStaticProps(args: any) { - return getStaticMarkdownProps(args, 'pages/draft-07'); -} - -export default function StaticMarkdownPage({ - frontmatter, - content, -}: { - frontmatter: any; - content: any; -}) { - const markdownFile = '_index'; - const newTitle = 'JSON Schema - ' + frontmatter.title; - - return ( - - - {newTitle} - - {frontmatter.title} - - - - ); -} -StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft-07/index.md b/pages/draft-07/index.md new file mode 100644 index 000000000..a0cb39366 --- /dev/null +++ b/pages/draft-07/index.md @@ -0,0 +1,33 @@ +--- +title: 'Draft-07' +Published: '19 March 2018' +type: docs +authors: ['Austin Wright', 'Henry Andrews'] +Metaschema: 'https://json-schema.org/draft-07/schema' +Specification: 'https://json-schema.org/draft-07/draft-handrews-json-schema-01.html' +--- + +### Introduction + +The JSON Schema Draft-07 introduces various updates to enhance the functionality of JSON Schemas in contrast to maintaining backward compatibility with Draft-06. + +### Draft-07 Documents + +- Core: [draft-handrews-json-schema-01](https://json-schema.org/draft-07/draft-handrews-json-schema-01.html) ([changes](https://json-schema.org/draft-07/draft-handrews-json-schema-01.html#rfc.appendix.B)) +- Validation: [draft-handrews-json-schema-validation-01](https://json-schema.org/draft-07/draft-handrews-json-schema-validation-01.html) ([changes](https://json-schema.org/draft-07/draft-handrews-json-schema-validation-01.html#rfc.appendix.B)) +- Hyper-Schema: [draft-handrews-json-schema-hyperschema-01](https://json-schema.org/draft-07/draft-handrews-json-schema-hyperschema-01.html) ([changes](https://json-schema.org/draft-07/draft-handrews-json-schema-hyperschema-01.html#rfc.appendix.B)) +- [JSON Schema meta-schema](https://json-schema.org/draft-07/schema) +- [JSON Hyper-Schema meta-schema](https://json-schema.org/draft-07/hyper-schema) +- [JSON Hyper-Schema Link Description Object meta-schema](https://json-schema.org/draft-07/links) +- [JSON Hyper-Schema recommended output schema](https://json-schema.org/draft-07/hyper-schema-output) +- Relative JSON Pointer: [draft-handrews-relative-json-pointer-01](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01) ([changes](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01#appendix-B)) +- Published: 19-March-2018 + +#### Obsolete Draft 7 Documents + +_These were updated without changing functionality or meta-schemas due to a few errors and unclear sections._ + +- Core: [draft-handrews-json-schema-00](https://json-schema.org/draft-07/draft-handrews-json-schema-00.pdf) ([changes](https://json-schema.org/draft-07/draft-handrews-json-schema-00.pdf#appendix-B)) +- Validation: [draft-handrews-json-schema-validation-00](https://json-schema.org/draft-07/draft-handrews-json-schema-validation-00.pdf) ([changes](https://json-schema.org/draft-07/draft-handrews-json-schema-validation-00.pdf#appendix-B)) +- Hyper-Schema: [draft-handrews-json-schema-hyperschema-00](https://json-schema.org/draft-07/draft-handrews-json-schema-hyperschema-00.html) ([changes](https://json-schema.org/draft-07/draft-handrews-json-schema-hyperschema-00.html#rfc.appendix.B)) +- Relative JSON Pointer: [draft-handrews-relative-json-pointer-00](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-00) ([changes](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-00#appendix-B)) diff --git a/pages/draft-07/index.page.tsx b/pages/draft-07/index.page.tsx new file mode 100644 index 000000000..8dd67863e --- /dev/null +++ b/pages/draft-07/index.page.tsx @@ -0,0 +1,61 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { SectionContext } from '~/context'; +import DocTable from '~/components/DocTable'; +import { Headline1 } from '~/components/Headlines'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync('pages/draft-07/index.md', 'utf-8'); + const main = fs.readFileSync( + 'pages/draft-07/json-schema-release-notes.md', + 'utf-8', + ); + const hyperSchema = fs.readFileSync( + 'pages/draft-07/json-hyper-schema-release-notes.md', + 'utf-8', + ); + const readme = fs.readFileSync('pages/draft-07/readme.md', 'utf-8'); + + const { content: indexContent, data: indexData } = matter(index); + const { content: bodyContent } = matter(main); + const { content: hyperSchemaContent } = matter(hyperSchema); + const { content: readmeContent } = matter(readme); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + body: bodyContent, + hyperSchema: hyperSchemaContent, + readme: readmeContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + + + + + + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/draft-07/json-hyper-schema-release-notes.md b/pages/draft-07/json-hyper-schema-release-notes.md index 4c7ec8ac5..fce0ec41e 100644 --- a/pages/draft-07/json-hyper-schema-release-notes.md +++ b/pages/draft-07/json-hyper-schema-release-notes.md @@ -1,7 +1,4 @@ ---- -title: JSON Hyper-Schema Draft-07 Release Notes -section: docs ---- +### JSON Hyper-Schema Draft-07 Release Notes JSON Hyper-Schema [draft-07](../../draft-07/json-schema-hypermedia.html) completes the reworking of Hyper-Schema that was begun in draft-06. @@ -12,56 +9,55 @@ so keywords used for other purposes (`readOnly` and `media`) have been The [new draft](../../draft-07/json-schema-hypermedia.html) has been completely rewritten for clarity and accessibility, so it is best to simply approach it as a new -proposal. We hope to add tutorial material at some point, but that is -outside of the scope of release notes. +proposal. However, if you wish to migrate from an earlier draft, this page is a guide -to the key _changes_. The additions, which are much more numerous, +to the key changes. The additions, which are much more numerous, should be learned directly from the new specification until we can provide tutorials. Note that draft-handrews-json-schema-hyperschema-00 has been replaced by draft-handrews-json-schema-hyperschema-01 in order to fix confusing -bugs. The newer -01 draft is **still considered to be draft-07**. +bugs. The newer -01 draft is **still considered to be draft-07**. It now references the draft-07 meta-schema with the correct URI, among -other typo fixes. There are no funcitonal changes between -00 and -01. +other typo fixes. There are no funcitonal changes between -00 and -01. -* [Migrating from draft-06](#migrating-from-draft-06) -* [Migrating from draft-05](#migrating-from-draft-05) -* [Migrating from draft-04](#migrating-from-draft-04) - * [GET](#get) - * [PUT](#put) - * [DELETE](#delete) - * [POST](#post) - * [PATCH](#patch) +- [Migrating from draft-06](#migrating-from-draft-06) +- [Migrating from draft-05](#migrating-from-draft-05) +- [Migrating from draft-04](#migrating-from-draft-04) + - [GET](#get) + - [PUT](#put) + - [DELETE](#delete) + - [POST](#post) + - [PATCH](#patch) -### Migrating from draft-06 +#### Migrating from draft-06 No draft-06 features were changed, although two keywords were renamed for clarity and consistency: -* `mediaType` -> `targetMediaType` -* `submissionEncType` -> `submissionMediaType` +- `mediaType` -> `targetMediaType` +- `submissionEncType` -> `submissionMediaType` Additionally, `hrefSchema` was somewhat confusing, so a great deal more effort has gone into explaining how it works, and how it fits into the overall link resolution process. -### Migrating from draft-05 +#### Migrating from draft-05 See the [draft-06 release notes](../../draft-06/json-hyper-schema-release-notes) for information related to draft-05. -### Migrating from draft-04 +#### Migrating from draft-04 In the ideal draft-07 world, links and [operations](https://json-schema.org/draft-07/json-schema-hypermedia.html#rfc.section.3.1) -are not the same concept. Using terminology borrowed from +are not the same concept. Using terminology borrowed from [OpenAPI's Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject), HTTP methods are operations, and each link (as described by a single LDO) can support multiple operations. Therefore, unlike draft-04, draft-07 hyper-schemas -[do not have separate links for each operation](../../draft-07/json-schema-hypermedia.html#rfc.section.8.1). This makes the migration guidelines below approximate at best. +[do not have separate links for each operation](../../draft-07/json-schema-hypermedia.html#rfc.section.8.1). This makes the migration guidelines below approximate at best. For a more detailed explanation of how draft-04's `method` and `targetSchema` were typically used to create single-operation links, and how that poses @@ -79,53 +75,53 @@ means that some uses of draft-04 do not have direct analogues in draft-07. Any keyword not mentioned in a list below is unchanged for that link operation. -#### GET +##### GET -* `"method": "GET"` -> `"targetHints": {"allow": ["GET"]}` -* `mediaType` -> `targetMediaType` -* `schema` -> `hrefSchema` with parameters added to `href` -* `encType` -> drop if `application/x-www-form-urlencoded`, contact the mailing list otherwise +- `"method": "GET"` -> `"targetHints": {"allow": ["GET"]}` +- `mediaType` -> `targetMediaType` +- `schema` -> `hrefSchema` with parameters added to `href` +- `encType` -> drop if `application/x-www-form-urlencoded`, contact the mailing list otherwise -#### PUT +##### PUT If you have a PUT link where `schema`/`encType` differ from `targetSchema`/`mediaType`, where `targetSchema`/`mediaType` describe a non-representation response, then those fields do not have a direct replacement. -* `"method": "PUT"` -> `"targetHints": {"allow": ["PUT"]}` -* `schema` -> `targetSchema` -* `encType` -> `targetMediaType` +- `"method": "PUT"` -> `"targetHints": {"allow": ["PUT"]}` +- `schema` -> `targetSchema` +- `encType` -> `targetMediaType` -#### DELETE +##### DELETE DELETE does not take a request payload, so `schema` and `encType` -should be unused. If `targetSchema` and `mediaType` were being +should be unused. If `targetSchema` and `mediaType` were being used for a response other than the just-deleted resource's representation, then they do not have a direct replacement. -* `"method": "DELETE"` -> `"targetHints": {"allow": ["DELETE"]}` -* `mediaType` -> `targetMediaType` (if describing the representation) +- `"method": "DELETE"` -> `"targetHints": {"allow": ["DELETE"]}` +- `mediaType` -> `targetMediaType` (if describing the representation) -#### POST +##### POST In most cases, the response of a POST is **not** a representation of the target resource, but rather some sort of result or status of whatever -the POST attempted to do. Therefore `targetSchema` and `mediaType` -should almost certainly be dropped. Other than that: +the POST attempted to do. Therefore `targetSchema` and `mediaType` +should almost certainly be dropped. Other than that: -* `"method": "POST"` -> `"targetHints": {"allow": ["POST"]}` -* `schema` -> `submissionSchema` -* `encType` -> `submissionMediaType` +- `"method": "POST"` -> `"targetHints": {"allow": ["POST"]}` +- `schema` -> `submissionSchema` +- `encType` -> `submissionMediaType` -#### PATCH +##### PATCH It was never entirely clear how to model a proper PATCH (that uses a patch media type rather than `application/json` in the request) in Hyper-Schema. One option was to treat it identically to PUT except with the patch media type -in `encType`. Assuming that approach (and the same `taregetSchema`/`mediaType` +in `encType`. Assuming that approach (and the same `taregetSchema`/`mediaType` caveats as for PUT): -* `"method": "PATCH"` -> `"targetHints": {"allow": ["PATCH"]}` -* `schema` -> `targetSchema` -* `"encType": "..."` -> `"targetHints": {"accept-patch": "..."}` +- `"method": "PATCH"` -> `"targetHints": {"allow": ["PATCH"]}` +- `schema` -> `targetSchema` +- `"encType": "..."` -> `"targetHints": {"accept-patch": "..."}` diff --git a/pages/draft-07/json-schema-release-notes.md b/pages/draft-07/json-schema-release-notes.md index 5d4fcbc89..afa5f98b5 100644 --- a/pages/draft-07/json-schema-release-notes.md +++ b/pages/draft-07/json-schema-release-notes.md @@ -1,128 +1,125 @@ ---- -title: Draft-07 Release Notes -section: docs ---- +### Draft-07 Release Notes For the Core and Validation specifications, draft-07 is a relatively -minor update. In terms of validation keywords and outcomes, it is fully +minor update. In terms of validation keywords and outcomes, it is fully backwards-compatible with draft-06. Some differences exist with keywords moved over from Hyper-Schema, and with -how instances and schemas are recommended to be linked together. Finally, +how instances and schemas are recommended to be linked together. Finally, the process of collecting annotation keyword values has been defined more clearly than before. -* [Keywords](#keywords) -* [Formats](#formats) -* [Classification of Keywords](#classification-of-keywords) -* [Collecting Annotation Values](#collecting-annotation-values) -* [JSON Schema in Hypermedia Environments](#json-schema-in-hypermedia-environments) - * [Linking Instances and Schemas](#linking-instances-and-schemas) - * [Instance Media Type](#instance-media-type) - -### Keywords - -* No keywords changed behavior -* No keywords were removed -* Some keywords were moved from Hyper-Schema, and two of those were renamed - -keyword | change | notes ----- | ---- | ---- -[`"$comment"`](../../draft-07/json-schema-core.html#rfc.section.9) | added to Core | Intended for notes to schema maintainers, as opposed to [`"description"`](../../draft-07/json-schema-validation.html#rfc.section.10.1) which is suitable for display to end users -[`"if"`, `"then"`, `"else"`](../../draft-07/json-schema-validation.html#rfc.section.6.6) | added to Validation | explicit conditional schema evaluation -[`"readOnly"`](../../draft-07/json-schema-validation.html#rfc.section.10.3) | moved from Hyper-Schema to Validation | not limited to hypermedia environments -[`"writeOnly"`](../../draft-07/json-schema-validation.html#rfc.section.10.3) | added to Validation | general write-only fields, including but not limited to passwords -[`"contentMediaType"`](../../draft-07/json-schema-validation.html#rfc.section.8) | moved from Hyper-Schema to Validation | formerly [`"media": {"type": "..."}`](../../draft-06/json-schema-hypermedia.html#rfc.section.5.3) -[`"contentEncoding"`](../../draft-07/json-schema-validation.html#rfc.section.8) | moved from Hyper-Schema to Validation | formerly [`"media": {"binaryEncoding": "..."}`](../../draft-06/json-schema-hypermedia.html#rfc.section.5.3) +- [Keywords](#keywords) +- [Formats](#formats) +- [Classification of Keywords](#classification-of-keywords) +- [Collecting Annotation Values](#collecting-annotation-values) +- [JSON Schema in Hypermedia Environments](#json-schema-in-hypermedia-environments) + - [Linking Instances and Schemas](#linking-instances-and-schemas) + - [Instance Media Type](#instance-media-type) + +#### Keywords + +- No keywords changed behavior +- No keywords were removed +- Some keywords were moved from Hyper-Schema, and two of those were renamed + +| keyword | change | notes | +| ---------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`"$comment"`](../../draft-07/json-schema-core.html#rfc.section.9) | added to Core | Intended for notes to schema maintainers, as opposed to [`"description"`](../../draft-07/json-schema-validation.html#rfc.section.10.1) which is suitable for display to end users | +| [`"if"`, `"then"`, `"else"`](../../draft-07/json-schema-validation.html#rfc.section.6.6) | added to Validation | explicit conditional schema evaluation | +| [`"readOnly"`](../../draft-07/json-schema-validation.html#rfc.section.10.3) | moved from Hyper-Schema to Validation | not limited to hypermedia environments | +| [`"writeOnly"`](../../draft-07/json-schema-validation.html#rfc.section.10.3) | added to Validation | general write-only fields, including but not limited to passwords | +| [`"contentMediaType"`](../../draft-07/json-schema-validation.html#rfc.section.8) | moved from Hyper-Schema to Validation | formerly [`"media": {"type": "..."}`](../../draft-06/json-schema-hypermedia.html#rfc.section.5.3) | +| [`"contentEncoding"`](../../draft-07/json-schema-validation.html#rfc.section.8) | moved from Hyper-Schema to Validation | formerly [`"media": {"binaryEncoding": "..."}`](../../draft-06/json-schema-hypermedia.html#rfc.section.5.3) | Note that the `"content*"` keywords do not _require_ validation. -### Formats +#### Formats Numerous formats were added, clarified, or restored from older drafts. -format | change | notes ----- | ---- | ---- -[`"iri"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.5) | added | I18N equivalent of `"uri"` -[`"iri-reference"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.5) | added | I18N equivalent of `"uri-reference"` -[`"uri-template"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.6) | noted IRI support | There is no separate IRI Template standard -[`"idn-email"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.2) | added | I18N equivalent of `"email"` -[`"idn-hostname"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.3) | added | I18N equivalent of `"hostname"` -[`"json-pointer"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.7) | clarified | Use for string form only, not URI fragment -[`"relative-json-pointer"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.7) | added | Revived [Relative JSON Pointer](../../draft-07/relative-json-pointer.html) draft -[`"regex"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.8) | restored from draft-03 | ECMA 262 regular expressions -[`"date"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.1) | restored from draft-03 | RFC 3339 "full-date" -[`"time"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.1) | restored from draft-03 | RFC 3339 "full-time" +| format | change | notes | +| ----------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------- | +| [`"iri"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.5) | added | I18N equivalent of `"uri"` | +| [`"iri-reference"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.5) | added | I18N equivalent of `"uri-reference"` | +| [`"uri-template"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.6) | noted IRI support | There is no separate IRI Template standard | +| [`"idn-email"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.2) | added | I18N equivalent of `"email"` | +| [`"idn-hostname"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.3) | added | I18N equivalent of `"hostname"` | +| [`"json-pointer"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.7) | clarified | Use for string form only, not URI fragment | +| [`"relative-json-pointer"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.7) | added | Revived [Relative JSON Pointer](../../draft-07/relative-json-pointer.html) draft | +| [`"regex"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.8) | restored from draft-03 | ECMA 262 regular expressions | +| [`"date"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.1) | restored from draft-03 | RFC 3339 "full-date" | +| [`"time"`](../../draft-07/json-schema-validation.html#rfc.section.7.3.1) | restored from draft-03 | RFC 3339 "full-time" | All other RFC 3339 date, time, and duration names are reserved for future -consideration. If added as extension formats, they SHOULD be implemented +consideration. If added as extension formats, they SHOULD be implemented in a way that is compatible with their use in the RFC to ensure future compatibility. -### Classification of Keywords +#### Classification of Keywords While it does not have a direct impact on the validation process, this set -of drafts classifies keywords by their behavior. The names of these +of drafts classifies keywords by their behavior. The names of these classifications are used throughout the documents, so they are useful to know: -* [Applicability](../../draft-07/json-schema-validation.html#rfc.section.3.1) -* [Assertions](../../draft-07/json-schema-validation.html#rfc.section.3.2) -* [Annotations](../../draft-07/json-schema-validation.html#rfc.section.3.3) +- [Applicability](../../draft-07/json-schema-validation.html#rfc.section.3.1) +- [Assertions](../../draft-07/json-schema-validation.html#rfc.section.3.2) +- [Annotations](../../draft-07/json-schema-validation.html#rfc.section.3.3) Note that `definitions` does not fit any of these categories, nor do the dollar-prefixed Core keywords. -### Collecting Annotation Values +#### Collecting Annotation Values [Annotation keywords](../../draft-07/json-schema-validation.html#rfc.section.10) (formerly called [metadata keywords](../../draft-06/json-schema-validation.html#rfc.section.7) now provide guidance on [how to collect multiple values](../../draft-07/json-schema-validation.html#rfc.section.3.3) -that apply to the same location in the instance. By default, all values +that apply to the same location in the instance. By default, all values that are not found within [negated schemas](../../draft-07/json-schema-validation.html#rfc.section.3.3.1) are collected -as an unordered set. The following exceptions are documented under the +as an unordered set. The following exceptions are documented under the approprite keywords: -* `readOnly` and `writeOnly` should be logically ORed -* `examples` should be flattened into a single collected array +- `readOnly` and `writeOnly` should be logically ORed +- `examples` should be flattened into a single collected array -### JSON Schema in Hypermedia Environments +#### JSON Schema in Hypermedia Environments These changes are not relevant to many Validation use cases, and are more -of interest to Hyper-Schema users. However, even without Hyper-Schema, +of interest to Hyper-Schema users. However, even without Hyper-Schema, if you are accessing instance documents over HTTP or through other hypermedia environments, you may find this section useful. -#### Linking Instances and Schemas +##### Linking Instances and Schemas After discussions with the author of the "profile" specification, we concluded -that its use for JSON Schema was not correct. The new guidance for +that its use for JSON Schema was not correct. The new guidance for [what relations to use](../../draft-07/json-schema-core.html#rfc.section.11.1) to link instances to schemas is: -link relation | change | notes ----- | ---- | ---- -"describedBy" | no change | network-accessible URL -"profile" | removed; use "schema" | opaque identifying URI -"schema" | added | opaque identifying URI +| link relation | change | notes | +| ------------- | --------------------- | ---------------------- | +| "describedBy" | no change | network-accessible URL | +| "profile" | removed; use "schema" | opaque identifying URI | +| "schema" | added | opaque identifying URI | "schema", like "profile" in past drafts, can also be used as a [media type parameter](../../draft-07/json-schema-core.html#rfc.section.11.2). -#### Instance Media Type +##### Instance Media Type Changes in the section are more relevant to JSON Hyper-Schema than to Validation, but as they are part of the core specification, they are explained here. Media types determine their own parameters, as well as their own -URI fragment syntax(es). `application/json` does not allow any parameters +URI fragment syntax(es). `application/json` does not allow any parameters or URI fragments. [`application/schema-instance+json`](../../draft-07/json-schema-core.html#rfc.section.4.2.2) - is an optional media type for use with instances that supports "schema" +is an optional media type for use with instances that supports "schema" as a media type parameter, and allows for URI fragments using the JSON Pointer syntax. diff --git a/pages/draft-07/readme.md b/pages/draft-07/readme.md index ad83f1017..a260bac9e 100644 --- a/pages/draft-07/readme.md +++ b/pages/draft-07/readme.md @@ -1,9 +1,5 @@ ---- -title: Draft-07 Release Notes -section: docs ---- +[JSON Schema Release Notes](/draft-07/json-schema-release-notes) -- [JSON Schema Release Notes](/draft-07/json-schema-release-notes) - [JSON Hyper-Schema Release Notes](/draft-07/json-hyper-schema-release-notes) -Note that the draft-handrews-\*-00 versions of JSON Hyper-Schema and Relative JSON Pointer had confusing bugs, and have been replaced by draft-handrews-\*-01 versions. The -00 versions may be found in the [obsolete](obsolete) directory. +Note that the draft-handrews-\*-00 versions of JSON Hyper-Schema and Relative JSON Pointer had confusing bugs, and have been replaced by draft-handrews-\*-01 versions. The -00 versions may be found in the [obsolete](obsolete) directory. diff --git a/pages/draft/2019-09/[slug].page.tsx b/pages/draft/2019-09/[slug].page.tsx deleted file mode 100644 index d7d289a2e..000000000 --- a/pages/draft/2019-09/[slug].page.tsx +++ /dev/null @@ -1,39 +0,0 @@ -import React from 'react'; -import Head from 'next/head'; -import { getLayout } from '~/components/Sidebar'; -import StyledMarkdown from '~/components/StyledMarkdown'; -import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; -import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; -import { Headline1 } from '~/components/Headlines'; -import { SectionContext } from '~/context'; -import { DocsHelp } from '~/components/DocsHelp'; - -export async function getStaticPaths() { - return getStaticMarkdownPaths('pages/draft/2019-09'); -} -export async function getStaticProps(args: any) { - return getStaticMarkdownProps(args, 'pages/draft/2019-09'); -} - -export default function StaticMarkdownPage({ - frontmatter, - content, -}: { - frontmatter: any; - content: any; -}) { - const markdownFile = '_index'; - const newTitle = 'JSON Schema - ' + frontmatter.title; - - return ( - - - {newTitle} - - {frontmatter.title} - - - - ); -} -StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft/2019-09/index.md b/pages/draft/2019-09/index.md new file mode 100644 index 000000000..35921345a --- /dev/null +++ b/pages/draft/2019-09/index.md @@ -0,0 +1,46 @@ +--- +title: Draft 2019-09 +section: docs +Specification: https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02.html +authors: + - Austin Wright + - Henry Andrews + - Ben Hutton + - Greg Dennis +Published: 17 September 2019 +Metaschema: https://json-schema.org/draft/2019-09/schema +--- + +### Introduction + +The JSON Schema Draft 2019-09 introduces updates and changes to improve the reliability of JSON Schema specifications. This draft builds upon previous versions. + +One significant update is the shift to HTTPS for all meta-schema URIs. While the URIs remain accessible over HTTP due to certain limitations, the recommended standard is now firmly HTTPS. + +### Draft 2019-09 Documents + +**\*NOTE:** All meta-schema URIs now use `https://`. While currently also available over plain HTTP due to the limitations of GitHub pages and the need to keep prior drafts available over HTTP, only the HTTPS URIs should be used.\* + +- Specifications + - Core: [draft-handrews-json-schema-02](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02.html) ([changes](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02.html#rfc.appendix.G)) + - Validation: [draft-handrews-json-schema-validation-02](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-validation-02.html) ([changes](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-validation-02.html#rfc.appendix.C)) + - Hyper-Schema: [draft-handrews-json-schema-hyperschema-02](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-hyperschema-02.html) ([changes](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-hyperschema-02.html#rfc.appendix.B)) + - Relative JSON Pointer: [draft-handrews-relative-json-pointer-02](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-02) ([changes](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-02#appendix-A)) + - Published: 17-September-2019 +- General use meta-schemas + - [JSON Schema meta-schema](https://json-schema.org/draft/2019-09/schema) + - [JSON Hyper-Schema meta-schema](https://json-schema.org/draft/2019-09/hyper-schema) + - [JSON Hyper-Schema Link Description Object meta-schema](https://json-schema.org/draft/2019-09/links) +- Individual vocabulary meta-schemas + - [Core Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/core) + - [Applicator Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/applicator) + - [Validation Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/validation) + - [Format Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/format) + - [Content Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/content) + - [Meta-Data Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/meta-data) + - [Hyper-Schema Vocabulary meta-schema](https://json-schema.org/draft/2019-09/meta/hyper-schema) +- Output schemas + - [JSON Schema recommended output schema](https://json-schema.org/draft/2019-09/output/schema) + - [JSON Hyper-Schema recommended output schema](https://json-schema.org/draft/2019-09/output/hyper-schema) +- Output examples + - [JSON Schema verbose output example](https://json-schema.org/draft/2019-09/output/verbose-example) diff --git a/pages/draft/2019-09/index.page.tsx b/pages/draft/2019-09/index.page.tsx new file mode 100644 index 000000000..20a512ec0 --- /dev/null +++ b/pages/draft/2019-09/index.page.tsx @@ -0,0 +1,46 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { SectionContext } from '~/context'; +import DocTable from '~/components/DocTable'; +import { Headline1 } from '~/components/Headlines'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync('pages/draft/2019-09/index.md', 'utf-8'); + const main = fs.readFileSync('pages/draft/2019-09/release-notes.md', 'utf-8'); + const { content: indexContent, data: indexData } = matter(index); + const { content: bodyContent } = matter(main); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + body: bodyContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + + + + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/draft/2019-09/release-notes.md b/pages/draft/2019-09/release-notes.md index a71d397b5..82b7d3948 100644 --- a/pages/draft/2019-09/release-notes.md +++ b/pages/draft/2019-09/release-notes.md @@ -1,68 +1,67 @@ ---- -title: 2019-09 Release Notes -section: docs ---- +### Draft 2019-09 Release Notes For the vast majority of schema authors, we hope that these changes are minimally disruptive. -The most likely to be frustrating is that `format` is no longer treated as a validation assertion _by default_ (although it is still possible for an application or user to configure a validator to treat it as one). We decided this was acceptable because many schema authors are already extremely frustrated by its inconsistent behavior. +The most likely to be frustrating is that `format` is no longer treated as a validation assertion *by default* (although it is still possible for an application or user to configure a validator to treat it as one). We decided this was acceptable because many schema authors are already extremely frustrated by its inconsistent behavior. For implementors, there is a lot more to consider, and further guidance on implementation topics will be forthcoming. -* [Incompatible Changes](#incompatible-changes) -* [Semi-incompatible Changes](#semi-incompatible-changes) -* [Annotations, Errors, and Outputs](#annotations-errors-and-outputs) -* [Keyword Changes](#keyword-changes) - * [Core Vocabulary](#core-vocabulary) - * [Applicator Vocabulary](#applicator-vocabulary) - * [Validation Vocabulary](#validation-vocabulary) - * [Format Vocabulary](#format-vocabulary) - * [Content Vocabulary](#content-vocabulary) - * [Meta-Data Vocabulary](#meta-data-vocabulary) - * [Hyper-Schema Vocabulary](#hyper-schema-vocabulary) + +- [Incompatible Changes](https://json-schema.org/draft/2019-09/release-notes#incompatible-changes) +- [Semi-incompatible Changes](https://json-schema.org/draft/2019-09/release-notes#semi-incompatible-changes) +- [Annotations, Errors, and Outputs](https://json-schema.org/draft/2019-09/release-notes#annotations-errors-and-outputs) +- [Keyword Changes](https://json-schema.org/draft/2019-09/release-notes#keyword-changes) + - [Core Vocabulary](https://json-schema.org/draft/2019-09/release-notes#core-vocabulary) + - [Applicator Vocabulary](https://json-schema.org/draft/2019-09/release-notes#applicator-vocabulary) + - [Validation Vocabulary](https://json-schema.org/draft/2019-09/release-notes#validation-vocabulary) + - [Format Vocabulary](https://json-schema.org/draft/2019-09/release-notes#format-vocabulary) + - [Content Vocabulary](https://json-schema.org/draft/2019-09/release-notes#content-vocabulary) + - [Meta-Data Vocabulary](https://json-schema.org/draft/2019-09/release-notes#meta-data-vocabulary) + - [Hyper-Schema Vocabulary](https://json-schema.org/draft/2019-09/release-notes#hyper-schema-vocabulary) For a basic list of changes to each document, see their change logs: -* [Core](../../draft/2019-09/json-schema-core.html#rfc.appendix.C) -* [Validation](../../draft/2019-09/json-schema-validation.html#rfc.appendix.C) -* [Hyper-Schema](../../draft/2019-09/json-schema-hypermedia.html#rfc.appendix.B) -### Incompatible Changes +- [Core](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.appendix.C) +- [Validation](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.appendix.C) +- [Hyper-Schema](https://json-schema.org/draft/2019-09/json-schema-hypermedia.html#rfc.appendix.B) + +#### Incompatible Changes -* 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. -* Plain name fragments are no longer defined with `$id`, but instead with the new keyword `$anchor` (which has a different syntax). -* `$id` cannot contain a fragment anymore (except possibly an empty fragment, although that is discouraged). -* 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. +- 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. +- Plain name fragments are no longer defined with `$id`, but instead with the new keyword `$anchor` (which has a different syntax). +- `$id` cannot contain a fragment anymore (except possibly an empty fragment, although that is discouraged). +- 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. -### Semi-incompatible Changes +#### Semi-incompatible Changes -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. +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. -* `definitions` is now `$defs` -* `dependencies` has been split into `dependentSchemas` and `dependentRequired` +- `definitions` is now `$defs` +- `dependencies` has been split into `dependentSchemas` and `dependentRequired` -### Annotations, Errors, and Outputs +#### Annotations, Errors, and Outputs -[Annotation keywords](../../draft/2019-09/json-schema-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. +[Annotation keywords](https://json-schema.org/draft/2019-09/json-schema-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. Similarly, there has not previously been guidance on what constitutes useful error reporting when validation fails. -To solve both of these problems, we now recommend that implementations support one or more of standardized [output formats](../../draft/2019-09/json-schema-core.html#rfc.section.10). +To solve both of these problems, we now recommend that implementations support one or more of standardized [output formats](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.10). -### Keyword Changes +#### Keyword Changes -All keywords have now been organized into [vocabularies](../../draft/2019-09/json-schema-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. +All keywords have now been organized into [vocabularies](https://json-schema.org/draft/2019-09/json-schema-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. #### Core Vocabulary [Core Specification, Section 8](../../draft/2019-09/json-schema-core.html#rfc.section.8) -keyword | change | notes ----- | ---- | ---- -[`$anchor`](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.3) | **new** | Replaces the `#plain-name` form of `$id`, with a different syntax and approach -[`$defs` (renamed from `definitions`)](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.5) | **renamed** | Note that the standard meta-schema still reserves `definitions` for backwards compatibility -[`$id`](../../draft/2019-09/json-schema-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 -[`$recursiveAnchor` and `$recursiveRef`](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.4.2) | **new** | Used for extending recursive schemas such as meta-schemas -[`$ref`](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.4) | **changed** | Other keywords are now allowed alongside of it -[`$vocabulary`](../../draft/2019-09/json-schema-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 +| keyword | change | notes | +| ------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`$anchor`](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.3) | **new** | Replaces the `#plain-name` form of `$id`, with a different syntax and approach | +| [`$defs` (renamed from `definitions`)](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.5) | **renamed** | Note that the standard meta-schema still reserves `definitions` for backwards compatibility | +| [`$id`](../../draft/2019-09/json-schema-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 | +| [`$recursiveAnchor` and `$recursiveRef`](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.4.2) | **new** | Used for extending recursive schemas such as meta-schemas | +| [`$ref`](../../draft/2019-09/json-schema-core.html#rfc.section.8.2.4) | **changed** | Other keywords are now allowed alongside of it | +| [`$vocabulary`](../../draft/2019-09/json-schema-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 | #### Applicator Vocabulary @@ -70,11 +69,11 @@ keyword | change | notes These keywords were formerly found in the Validation Specification. -keyword | change | notes ----- | ---- | ---- -[`dependentSchemas` (split from `dependencies`)](../../draft/2019-09/json-schema-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 -[`unevaluatedItems`](../../draft/2019-09/json-schema-core.html#rfc.section.9.3.1.3) | **new** | Similar to `additionalItems`, but can "see" into subschemas and across references -[`unevaluatedProperties`](../../draft/2019-09/json-schema-core.html#rfc.section.9.3.2.4) | **new** | Similar to `additionalProperties`, but can "see" into subschemas and across references +| keyword | change | notes | +| --------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| [`dependentSchemas` (split from `dependencies`)](../../draft/2019-09/json-schema-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 | +| [`unevaluatedItems`](../../draft/2019-09/json-schema-core.html#rfc.section.9.3.1.3) | **new** | Similar to `additionalItems`, but can "see" into subschemas and across references | +| [`unevaluatedProperties`](../../draft/2019-09/json-schema-core.html#rfc.section.9.3.2.4) | **new** | Similar to `additionalProperties`, but can "see" into subschemas and across references | The other applicator vocabulary keywords are `items`, `additionalItems`, `properties`, `patternProperties`, `additionalProperties`, `anyOf`, `allOf`, `oneOf`, `not`, `if`, `then`, `else`. @@ -82,91 +81,89 @@ The other applicator vocabulary keywords are `items`, `additionalItems`, `proper [Validation Specification, Section 6](../../draft/2019-09/json-schema-validation.html#rfc.section.6) -keyword | change | notes ----- | ---- | ---- -[`dependentRequired` (split from `dependencies`)](../../draft/2019-09/json-schema-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 -[`maxContains` and `minContains`](../../draft/2019-09/json-schema-validation.html#rfc.section.6.4.4) | **new** | Assertion for controlling how many times a subschema must be matched within an array - +| keyword | change | notes | +| -------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [`dependentRequired` (split from `dependencies`)](../../draft/2019-09/json-schema-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 | +| [`maxContains` and `minContains`](../../draft/2019-09/json-schema-validation.html#rfc.section.6.4.4) | **new** | Assertion for controlling how many times a subschema must be matched within an array | #### Format Vocabulary [Validation Specification, Section 7](../../draft/2019-09/json-schema-validation.html#rfc.section.7) -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. +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. -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](../../draft/2019-09/json-schema-core.html#rfc.section.7.7) and supporting the [basic, detailed, or verbose output formats](../../draft/2019-09/json-schema-core.html#rfc.section.10.4.2). +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](../../draft/2019-09/json-schema-core.html#rfc.section.7.7) and supporting the [basic, detailed, or verbose output formats](../../draft/2019-09/json-schema-core.html#rfc.section.10.4.2). -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. +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. -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). +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). **Summary of draft-07 behavior** -supported | configuration | outcome ------------ | ------------- | ------------- -no | n/a | not validated -yes | _default_ (on)| inconsistently validated -yes | off | not validated +| supported | configuration | outcome | +| --------- | -------------- | ------------------------ | +| no | n/a | not validated | +| yes | _default_ (on) | inconsistently validated | +| yes | off | not validated | -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. +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. **Summary of 2019-09 behavior** -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. +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. -* "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. +- "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. -* "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. +- "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. -* An outcome of _vocabulary error_ means that the implementation will refuse to process the schema as it cannot satisfy the vocabulary requirement. +- An outcome of _vocabulary error_ means that the implementation will refuse to process the schema as it cannot satisfy the vocabulary requirement. -supported | configuration | vocabulary | outcome ------------ | -------------- | ------------- | ------------- -no | n/a | false | not validated -no | n/a | true | _vocabulary error_ -best effort | _default_ (off)| false | not validated -best effort | _default_ (off)| true | _vocabulary error_ -best effort | on | false | best effort validation -best effort | on | true | _vocabulary error_ -full syntax | _default_ (off)| false | not validated -full syntax | _default_ (off)| true | full syntax validation -full syntax | on | false | full syntax validation -full syntax | on | true | full syntax validation +| supported | configuration | vocabulary | outcome | +| ----------- | --------------- | ---------- | ---------------------- | +| no | n/a | false | not validated | +| no | n/a | true | _vocabulary error_ | +| best effort | _default_ (off) | false | not validated | +| best effort | _default_ (off) | true | _vocabulary error_ | +| best effort | on | false | best effort validation | +| best effort | on | true | _vocabulary error_ | +| full syntax | _default_ (off) | false | not validated | +| full syntax | _default_ (off) | true | full syntax validation | +| full syntax | on | false | full syntax validation | +| full syntax | on | true | full syntax validation | -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. +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. Additionally, two new formats were added, and a specification reference was updated: -format | change | notes ----- | ---- | ---- -[`"duration"`](../../draft/2019-09/json-schema-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 -[`"hostname"` and `"idn-hostname"`](../../draft/2019-09/json-schema-validation.html#rfc.section.7.3.3) | **updated** | Use RFC 1123 instead of RFC 1034; this allows for a leading digit -[`"uuid"`](../../draft/2019-09/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 - +| format | change | notes | +| ------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ | +| [`"duration"`](../../draft/2019-09/json-schema-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 | +| [`"hostname"` and `"idn-hostname"`](../../draft/2019-09/json-schema-validation.html#rfc.section.7.3.3) | **updated** | Use RFC 1123 instead of RFC 1034; this allows for a leading digit | +| [`"uuid"`](../../draft/2019-09/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 | #### Content Vocabulary [Validation Specification, Section 8](../../draft/2019-09/json-schema-validation.html#rfc.section.8) -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. +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. -keyword | change | notes ----- | ---- | ---- -[`contentEncoding`](../../draft/2019-09/json-schema-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 -[`contentSchema`](../../draft/2019-09/json-schema-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 +| keyword | change | notes | +| ------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`contentEncoding`](../../draft/2019-09/json-schema-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 | +| [`contentSchema`](../../draft/2019-09/json-schema-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 | #### Meta-Data Vocabulary [Validation Specification, Section 9](../../draft/2019-09/json-schema-validation.html#rfc.section.9) -keyword | change | notes ----- | ---- | ---- -[`deprecated`](../../draft/2019-09/json-schema-validation.html#rfc.section.9.3) | **added** | Used to indicate that a field is deprecated in some application-specific manner +| keyword | change | notes | +| ------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | +| [`deprecated`](../../draft/2019-09/json-schema-validation.html#rfc.section.9.3) | **added** | Used to indicate that a field is deprecated in some application-specific manner | #### Hyper-Schema Vocabulary [Hyper-Schema Specification, Sections 5 and 6](../../draft/2019-09/json-schema-hypermedia.html#rfc.section.5) -keyword | change | notes ----- | ---- | ---- -[`rel`](../../draft/2019-09/json-schema-hypermedia.html#rfc.section.6.2.1) | **changed** | Can now be an array of values instead of just a string +| keyword | change | notes | +| -------------------------------------------------------------------------- | ----------- | ------------------------------------------------------ | +| [`rel`](../../draft/2019-09/json-schema-hypermedia.html#rfc.section.6.2.1) | **changed** | Can now be an array of values instead of just a string | diff --git a/pages/draft/2020-12/[slug].page.tsx b/pages/draft/2020-12/[slug].page.tsx deleted file mode 100644 index 52734da09..000000000 --- a/pages/draft/2020-12/[slug].page.tsx +++ /dev/null @@ -1,39 +0,0 @@ -import React from 'react'; -import Head from 'next/head'; -import { getLayout } from '~/components/Sidebar'; -import StyledMarkdown from '~/components/StyledMarkdown'; -import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; -import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; -import { Headline1 } from '~/components/Headlines'; -import { SectionContext } from '~/context'; -import { DocsHelp } from '~/components/DocsHelp'; - -export async function getStaticPaths() { - return getStaticMarkdownPaths('pages/draft/2020-12'); -} -export async function getStaticProps(args: any) { - return getStaticMarkdownProps(args, 'pages/draft/2020-12'); -} - -export default function StaticMarkdownPage({ - frontmatter, - content, -}: { - frontmatter: any; - content: any; -}) { - const markdownFile = '_index'; - const newTitle = 'JSON Schema - ' + frontmatter.title; - - return ( - - - {newTitle} - - {frontmatter.title} - - - - ); -} -StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft/2020-12/index.md b/pages/draft/2020-12/index.md new file mode 100644 index 000000000..5be03ef7e --- /dev/null +++ b/pages/draft/2020-12/index.md @@ -0,0 +1,54 @@ +--- +title: 'Draft 2020-12' +Published: '16 June 2022' +type: docs +authors: ['Austin Wright', 'Henry Andrews', 'Ben Hutton', 'Greg Dennis'] +Metaschema: 'https://json-schema.org/draft/2020-12/schema' +Specification: 'https://json-schema.org/draft/2020-12/json-schema-core.html' +--- + +### Introduction + +The JSON Schema Draft 2020-12 is a comprehensive update to the previous [draft 2019-09](draft/2019-09), addressing feedback and implementation experiences. This draft introduces features to simplify creating and validating JSON schemas. + +Here's an overview of updates to Draft 2020-12; + +- **Redesigned Array and Tuple Keywords**: The `items` and `additionalItems` keywords have been replaced by `prefixItems` and `items`. +- **Dynamic References**: The introduction of `$dynamicRef` and `$dynamicAnchor` replaces the older `$recursiveRef` and `$recursiveAnchor`. +- **Contains and UnevaluatedItems**: Specifies how the `contains` keyword affects the `unevaluatedItems` keyword. +- **Regular Expressions**: Now expected to support Unicode characters, addressing inconsistencies in previous drafts. +- **Media Type Changes**: Drops the schema media type parameter. +- **Embedded Schemas and Bundling**: Provides guidance on bundling schemas into a Compound Schema Document. +- **Vocabulary Changes**: Separates the `format` vocabulary into `format-annotation` and `format-assertion`. + +### Draft 2020-12 Documents + +- Specifications + - Core: [draft-bhutton-json-schema-01](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-01.html) ([changes](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-01.html#appendix-G)) + - Validation: [draft-bhutton-json-schema-validation-01](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-01.html) ([changes](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-01.html#appendix-C)) + - Relative JSON Pointer: [draft-bhutton-relative-json-pointer-00](https://tools.ietf.org/html/draft-bhutton-relative-json-pointer-00) ([changes](https://tools.ietf.org/html/draft-bhutton-relative-json-pointer-00#appendix-A)) + - Published: 16-June-2022 +- General use meta-schemas + - [JSON Schema meta-schema](https://json-schema.org/draft/2020-12/schema) + - [JSON Hyper-Schema meta-schema](https://json-schema.org/draft/2020-12/hyper-schema) (2019-09 Hyper-Schema with 2020-12 Validation) + - [JSON Hyper-Schema Link Description Object meta-schema](https://json-schema.org/draft/2020-12/links) +- Individual vocabulary meta-schemas + - [Core Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/core) + - [Applicator Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/applicator) + - [Validation Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/validation) + - [Unevaluated Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/unevaluated) + - [Format Annotation Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/format-annotation) + - [Format Assertion Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/format-assertion) + - [Content Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/content) + - [Meta-Data Vocabulary meta-schema](https://json-schema.org/draft/2020-12/meta/meta-data) +- Output schemas + - [JSON Schema recommended output schema](https://json-schema.org/draft/2020-12/output/schema) +- Output examples + - [JSON Schema verbose output example](https://json-schema.org/draft/2020-12/output/verbose-example) + +#### Obsolete Draft 2020-12 Documents + +_These were updated without changing functionality or meta-schemas due to a few errors and unclear sections._ + +- Core: [draft-bhutton-json-schema-00](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00.html) ([changes](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00.html#rfc.appendix.G)) +- Validation: [draft-bhutton-json-schema-validation-00](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00.html) ([changes](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00.html#rfc.appendix.C)) diff --git a/pages/draft/2020-12/index.page.tsx b/pages/draft/2020-12/index.page.tsx new file mode 100644 index 000000000..90892f938 --- /dev/null +++ b/pages/draft/2020-12/index.page.tsx @@ -0,0 +1,46 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { SectionContext } from '~/context'; +import DocTable from '~/components/DocTable'; +import { Headline1 } from '~/components/Headlines'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync('pages/draft/2020-12/index.md', 'utf-8'); + const main = fs.readFileSync('pages/draft/2020-12/release-notes.md', 'utf-8'); + const { content: indexContent, data: indexData } = matter(index); + const { content: bodyContent } = matter(main); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + body: bodyContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + + + + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/draft/2020-12/release-notes.md b/pages/draft/2020-12/release-notes.md index cd04ba966..c6269a20b 100644 --- a/pages/draft/2020-12/release-notes.md +++ b/pages/draft/2020-12/release-notes.md @@ -1,7 +1,5 @@ ---- -title: 2020-12 Release Notes -section: docs ---- +### Draft 2020-12 Release Notes + The previous draft (2019-09) introduced a lot of new concepts including `$recursiveRef`/`$recursiveAnchor`, `unevaluatedProperties`/`unevaluatedItems`, vocabularies, and more. Since then, these new features have seen multiple @@ -12,7 +10,8 @@ using these new features in the wild. This document attempts to put information most useful to schema authors toward the top and information for implementation authors toward the bottom. -## Changes to items and additionalItems +#### Changes to items and additionalItems + The keywords used for defining arrays and tuples have been redesigned to help lower the learning curve for JSON Schema. Since the `items` keyword was used for both types, we would often see people mistakenly defining a tuple when they @@ -31,7 +30,8 @@ items that come before the normal items (`prefixItems`). Here are some examples to illustrate the changes. -### Open tuple +##### Open tuple + @@ -63,7 +63,8 @@ Here are some examples to illustrate the changes.
-### Closed tuple +##### Closed tuple + @@ -97,7 +98,8 @@ Here are some examples to illustrate the changes.
-### Tuple with constrained additional items +##### Tuple with constrained additional items + @@ -131,7 +133,8 @@ Here are some examples to illustrate the changes.
-## $dynamicRef and $dynamicAnchor +#### $dynamicRef and $dynamicAnchor + The `$recursiveRef` and `$recursiveAnchor` keywords were replaced by the more powerful `$dynamicRef` and `$dynamicAnchor` keywords. `$recursiveRef` and `$recursiveAnchor` were introduced in the previous draft to solve the problem of @@ -187,6 +190,7 @@ Here's how you would covert a schema using `$recursiveRef` to use `$dynamicRef`. "unevaluatedProperties": false } ``` + @@ -214,14 +218,14 @@ Here's how you would covert a schema using `$recursiveRef` to use `$dynamicRef`. "unevaluatedProperties": false } ``` + +#### contains and unevaluatedItems - -## contains and unevaluatedItems In the previous draft, it wasn't specified how or if the `contains` keyword affects the `unevaluatedItems` keyword. This draft specifies that any item in an array that passes validation of the `contains` schema is considered "evaluated". @@ -317,19 +321,22 @@ Given this schema, the instance `["a", "b", "ccc"]` will fail because `"ccc"` is considered unevaluated and fails the `unevaluatedItems` keyword like it did in previous drafts. -## Regular Expressions +#### Regular Expressions + Regular expressions are now expected (but not strictly required) to support unicode characters. Previously, this was unspecified and implementations may or may not support this unicode in regular expressions. -## Media Type Changes +#### Media Type Changes + JSON Schema defines two media types, `application/schema+json` and `application/schema-instance+json`. This draft drops support for the `schema` media type parameter. It's caused a lot of confusion and disagreement. Since we haven't seen any evidence of anyone actually using it, it was decided to remove it for now. -## Embedded Schemas and Bundling +#### Embedded Schemas and Bundling + In Draft 2019-09, the meaning of `$id` in a sub-schema changed from indicating a base URI change within the current schema to indicating an embedded schema independent of the parent schema. A schema that contains one or more embedded @@ -400,7 +407,7 @@ external references that we want to bundle. "$defs": { "phone": { "type": "string", - "pattern": "^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$" + "pattern": "^[+]?[(]?[0-9]{3}[)]?[-s.]?[0-9]{3}[-s.]?[0-9]{4,6}$" }, "usaPostalCode": { "type": "string", @@ -474,24 +481,26 @@ Here are a few things you might notice from this example. 1. No `$ref`s were modified. Even local references are unchanged. 2. `https://example.com/schema/common#/` -`$defs/unsignedInt` got pulled in with the -common schema even though it isn't used. It's allowed to trim out the extra -definitions, but not necessary. + `$defs/unsignedInt` got pulled in with the + common schema even though it isn't used. It's allowed to trim out the extra + definitions, but not necessary. 3. `https://example.com/schema/address` doesn't declare a `$schema`. Because it -uses the same `$schema` as `https://example.com/schema/customer`, it can skip -that declaration and use the `$schema` from the schema it's embedded in. + uses the same `$schema` as `https://example.com/schema/customer`, it can skip + that declaration and use the `$schema` from the schema it's embedded in. 4. `https://example.com/schema/common` uses a different `$schema` than the -document it's embedded in. That's allowed. + document it's embedded in. That's allowed. 5. Definitions from `https://example.com/schema/common` are used in both of the -other schemas and only needs to be included once. It isn't necessary for -bundlers to embed a schema inside another embedded schema. + other schemas and only needs to be included once. It isn't necessary for + bundlers to embed a schema inside another embedded schema. + +#### Annotations -## Annotations Implementations that collect annotations should now include annotations for unknown keywords in the "verbose" output format. The annotation value for an unknown keyword is the keyword's value. -## Vocabulary Changes +#### Vocabulary Changes + The `unevaluatedProperties` and `unevaluatedItems` keywords have been moved from the applicator vocabulary to their own designated vocabulary which is required in the default meta-schema. In Draft 2019-09, these keywords were expected to diff --git a/pages/specification/json-hyper-schema/index.md b/pages/specification/json-hyper-schema/index.md new file mode 100644 index 000000000..b116253a7 --- /dev/null +++ b/pages/specification/json-hyper-schema/index.md @@ -0,0 +1,33 @@ +--- +title: JSON Hyper-Schema +--- + +### Introduction + +JSON Hyper-Schema is an extension of JSON Schema that allows for the definition of hypermedia-driven APIs. The hyper-schema vocabulary shows how to annotate JSON documents with hypermedia controls by enabling the description of links and actions that can be executed on JSON data. Consecutively, it helps provide a more interactive and dynamic representation of JSON data. It also enhances API discoverability using the description features of actions and links within the JSON documents. + +JSON Hyper-Schema seamlessly integrates with existing JSON HTTP APIs and offers functionalities to describe complex resource relationships, facilitate client-side validation, and promote better interaction patterns. It makes APIs more intuitive, self-descriptive, and efficient, particularly in RESTful architectures. + +In essence: + +- JSON Hyper-Schema is helpful in complex APIs where clients need to define and explicitly understand the relationships between resources and actions, especially when navigating resources without prior knowledge of the API structure. +- It helps create more discoverable and self-documenting APIs, making it easier for clients to interact with them. + +### Hyper Schema Documents + +- Hyper-Schema: [jsonschema-hyperschema.xml](https://github.com/json-schema-org/json-hyperschema-spec/blob/main/jsonschema-hyperschema.xml) +- Relative JSON Pointer: [relative-json-pointer.xml](https://github.com/json-schema-org/json-schema-spec/blob/master/relative-json-pointer.xml) + +**Other documents:** + +- [JSON Schema meta-schema](https://github.com/json-schema-org/json-schema-spec/blob/master/schema.json) +- [JSON Hyper-Schema meta-schema](https://github.com/json-schema-org/json-hyperschema-spec/blob/main/hyper-schema.json) +- [JSON Hyper-Schema Link Description Object meta-schema](https://github.com/json-schema-org/json-hyperschema-spec/blob/main/links.json) +- [JSON Schema Vocabulary meta-schemas](https://github.com/json-schema-org/json-hyperschema-spec/tree/main/meta/) +- [JSON Schema Output schemas and examples](https://github.com/json-schema-org/json-hyperschema-spec/tree/main/output/) + +### Release Notes + +- [Draft-07 to 2019-09](../draft/2019-09#hyper-schema-vocabulary) +- [Draft-04 to Draft-07](../draft-07#json-hyper-schema-draft-07-release-notes) +- [Draft-04 to Draft-06](../draft-06#json-hyper-schema-draft-06-release-notes) diff --git a/pages/specification/json-hyper-schema/index.page.tsx b/pages/specification/json-hyper-schema/index.page.tsx new file mode 100644 index 000000000..bcf365031 --- /dev/null +++ b/pages/specification/json-hyper-schema/index.page.tsx @@ -0,0 +1,48 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { SectionContext } from '~/context'; +import { Headline1 } from '~/components/Headlines'; + +export async function getStaticProps() { + const index = fs.readFileSync( + 'pages/specification/json-hyper-schema/index.md', + 'utf-8', + ); + // const main = fs.readFileSync('pages/draft-05/release-notes.md', 'utf-8'); + const { content: indexContent, data: indexData } = matter(index); + // const { content: bodyContent } = matter(main); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + // body: bodyContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} +

{frontmatter.type}

+

{frontmatter.Specification}

+ + + + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/specification/migration/index.page.tsx b/pages/specification/migration/index.page.tsx new file mode 100644 index 000000000..f057ada5f --- /dev/null +++ b/pages/specification/migration/index.page.tsx @@ -0,0 +1,78 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { Headline1 } from '~/components/Headlines'; +import { SectionContext } from '~/context'; +import Card from '~/components/Card'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync( + 'pages/specification/migration/intro.md', + 'utf-8', + ); + // const main = fs.readFileSync('pages/draft-05/release-notes.md', 'utf-8'); + const { content: indexContent, data: indexData } = matter(index); + // const { content: bodyContent } = matter(main); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + // body: bodyContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + +
+ + + + +
+ + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/specification/migration/intro.md b/pages/specification/migration/intro.md new file mode 100644 index 000000000..734bd0b33 --- /dev/null +++ b/pages/specification/migration/intro.md @@ -0,0 +1,7 @@ +--- +title: Migrating from older drafts +section: docs +--- + +The release notes discuss the changes impacting users and implementers: + diff --git a/pages/specification/release-notes/index.page.tsx b/pages/specification/release-notes/index.page.tsx new file mode 100644 index 000000000..f5ef9359d --- /dev/null +++ b/pages/specification/release-notes/index.page.tsx @@ -0,0 +1,85 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import fs from 'fs'; +import matter from 'gray-matter'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { Headline1 } from '~/components/Headlines'; +import { SectionContext } from '~/context'; +import Card from '~/components/Card'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticProps() { + const index = fs.readFileSync( + 'pages/specification/release-notes/intro.md', + 'utf-8', + ); + // const main = fs.readFileSync('pages/draft-05/release-notes.md', 'utf-8'); + const { content: indexContent, data: indexData } = matter(index); + // const { content: bodyContent } = matter(main); + + const frontmatter = { ...indexData }; + return { + props: { + blocks: { + index: indexContent, + // body: bodyContent, + }, + frontmatter, + }, + }; +} + +export default function ImplementationsPages({ + blocks, + frontmatter, +}: { + blocks: any; + frontmatter: any; +}) { + return ( + + {frontmatter.title} + + +
+ + + + + +
+ + + ); +} +ImplementationsPages.getLayout = getLayout; diff --git a/pages/specification/release-notes/intro.md b/pages/specification/release-notes/intro.md new file mode 100644 index 000000000..bfe2815c1 --- /dev/null +++ b/pages/specification/release-notes/intro.md @@ -0,0 +1,6 @@ +--- +title: Release notes +type: docs +--- + +Find below the Release Notes of all JSON Schema drafts: diff --git a/public/_redirects b/public/_redirects index 6282f8c5a..5cb005d33 100644 --- a/public/_redirects +++ b/public/_redirects @@ -23,3 +23,8 @@ /slack https://join.slack.com/t/json-schema/shared_invite/zt-2n5bzzgx3-ro3V0mnnzUoaguILLosT2A 301 /slack-redirect https://join.slack.com/t/json-schema/shared_invite/zt-2n5bzzgx3-ro3V0mnnzUoaguILLosT2A 301 /ambassadors https://github.com/json-schema-org/community/tree/main/programs/ambassadors 301 +/draft/2020-12/release-notes /draft/2020-12#draft-2020-12-release-notes 301 +/draft/2019-09/release-notes /draft/2019-09#draft-2019-09-release-notes 301 +/draft-07/json-schema-release-notes /draft-07#draft-07-release-notes 301 +/draft-06/json-schema-release-notes /draft-06#draft-06-release-notes 301 +/draft-05/readme /draft-05#explanation-for-lack-of-draft-05-meta-schemas 301