Fix: #7. Add JSON Schema media types (#19)

* Add JSON Schema media types

draft-ietf-httpapi-rest-api-mediatypes.md

@@ -39,6 +39,15 @@ normative:
     - ins: Mike Ralphson
     - ins: Ron Ratovsky
     - ins: Uri Sarid
+  jsonschema:
+    title: JSON Schema Core
+    date: 2020-01-28
+    target: "https://json-schema.org/specification.html"
+    author:
+    - ins: A. Wright
+    - ins: H. Andrews
+    - ins: B. Hutton
+    - ins: G. Dennis
 
 informative:
 
@@ -48,6 +57,8 @@ This document registers
 the following media types used in APIs
 on the IANA Media Types registry:
 application/yaml,
+application/schema+json,
+application/schema-instance+json,
 application/openapi+json,
 and application/openapi+yaml.
 
@@ -75,6 +86,8 @@ and leverage content negotiation mechanisms when exchanging
 OpenAPI Specification resources
 this specification register the following media-types:
 `application/yaml`,
+`application/schema+json`,
+`application/schema-instance+json`,
 `application/openapi+json`
 and `application/openapi+yaml`.
 
@@ -301,6 +314,239 @@ Author:  See Authors' Addresses section
 
 Change controller:  n/a
 
+## JSON Schema Media Types
+
+JSON Schema is a declarative domain-specific language for validating and
+annotating JSON documents (see {{jsonschema}}).
+
+This document registers the media types associated with JSON Schema.
+
+There are many dialects of JSON Schema in wide use today. The JSON Schema
+maintainers have released several dialects including draft-04, draft-07, and
+draft 2020-12. There are also several third-party JSON Schema dialects in wide
+use including the ones defined for use in OpenAPI and MongoDB.
+
+This specification defines little more than how to identify the dialect while
+leaving most of the semantics of the schema up to the dialect to define. Clients
+MUST use the following order of precedence for determining the dialect of a
+schema.
+
+* The `$schema` keyword ({{schema-keyword}})
+* The "schema" media type parameter ({{schema-parameter}})
+* The context of the enclosing document. This applies only when a schema is
+  embedded within a document. The enclosing document could be another schema in
+  the case of a bundled schema or it could be another type of document that
+  includes schemas such as an OpenAPI document.
+* If none of the above result in identifying the dialect, client behavior is
+  undefined.
+
+### The "$schema" Keyword {#schema-keyword}
+
+The `$schema` keyword is used as a JSON Schema dialect identifier. The value of
+this keyword MUST be a URI {{!RFC3986}}. This URI SHOULD identify a meta-schema
+that can be used to validate that the schema is syntactically correct according
+to the dialect the URI identifies.
+
+The dialect SHOULD define where the `$schema` keyword is allowed and/or
+recognized in a schema, but it is RECOMMENDED that dialects do not allow the
+schema to change within the same Schema Resource.
+
+### Identifying a Schema via a Media Type Parameter {#schema-parameter}
+
+Media types MAY allow for a `schema` media type parameter, to support content
+negotiation based on schema identifier (see Section 12 of {{!SEMANTICS=RFC7231}}).
+The `schema` media type parameter MUST be a URI-reference {{!RFC3986}}.
+
+The `schema` parameter identifies a schema that provides semantic information
+about the resource the media type represents. When using the
+`application/schema+json` media type, the `schema` parameter identifies the
+dialect of the schema the media type represents.
+
+The `schema` URI is opaque and SHOULD NOT automatically be dereferenced. Since
+`schema` doesn't necessarily point to a network location, the "describedby"
+relation is used for linking to a downloadable schema.
+
+The following is an example of content negotiation where a user agent can accept
+two different versions of a "pet" resource. Each resource version is identified
+by a unique JSON Schema.
+
+Request:
+
+~~~ http-message
+GET /pet/1234 HTTP/1.1
+Accept: application/schema-instance+json; schema="/schemas/v2/pet"; q=0.2,
+        application/schema-instance+json; schema="/schemas/v1/pet"; q=0.1
+~~~
+
+Response:
+
+~~~ http-message
+HTTP/1.1 200 Ok
+Content-Type: application/schema-instance+json; schema="/schemas/v2/pet"
+
+{
+  "petId": "1234",
+  "name": "Pluto",
+  ...
+}
+~~~
+
+In the following example, the user agent is able to accept two possible dialects
+of JSON Schema and the server replies with the latest one.
+
+Request:
+
+~~~ http-message
+GET /schemas/v2/pet HTTP/1.1
+Accept: application/schema+json; schema="https://json-schema.org/draft/2020-12/schema",
+        application/schema+json; schema="http://json-schema.org/draft-07/schema#"
+~~~
+
+Response:
+
+~~~ http-message
+HTTP/1.1 200 OK
+Content-Type: application/schema+json; schema="https://json-schema.org/draft/2020-12/schema"
+
+{
+  "$id": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  ...
+}
+~~~
+
+### Linking to a Schema {#schema-linking}
+
+It is RECOMMENDED that instances described by a schema provide a link to a
+downloadable JSON Schema using the link relation `describedby`, as defined by
+Linked Data Protocol 1.0, section 8.1 {{!W3C.REC-ldp-20150226}}.
+
+In HTTP, such links can be attached to any response using the `Link` header
+{{!LINK=RFC8288}}.
+
+~~~
+Link: <https://example.com/my-hyper-schema#>; rel="describedby"
+~~~
+
+### Fragment Identifiers {#schema-fragment}
+
+Two fragment identifier structures are supported: JSON Pointers and plain-names.
+
+The use of JSON Pointers as URI fragment identifiers is described in RFC 6901
+{{!RFC6901}}. Fragment identifiers that are empty or start with a `/`, MUST be
+interpreted as JSON Pointer fragment identifiers.
+
+Plain-name fragment identifiers reference locally named locations in the
+document. The dialect determines how plain-name identifiers map to locations
+within the document. All fragment identifiers that do not match the JSON Pointer
+syntax MUST be interpreted as plain name fragment identifiers.
+
+### Media Type application/schema+json {#schema-json}
+
+The `application/schema+json` media type represents JSON Schema. This schema can
+be an official dialect or a third-party dialect. The following information
+serves as the registration form for the `application/schema+json` media type.
+
+**Type name**: application
+
+**Subtype name**: schema+json
+
+**Required parameters**: N/A
+
+**Optional parameters**:
+
+* **schema**: A URI identifying the JSON Schema dialect the schema was written
+  for. If this value conflicts with the value of the `$schema` keyword in the
+  schema, the `$schema` keyword takes precedence.
+
+**Encoding considerations**: Same as {{JSON}}
+
+**Security considerations**: See the "Security Considerations" section of
+{{jsonschema}}
+
+**Interoperability considerations**: See the "General Considerations" section of
+{{jsonschema}}
+
+**Published specification**: (this document)
+
+**Applications that use this media type**: JSON Schema is used in a variety of
+applications including API servers and clients that validate JSON requests and
+responses, IDEs that valid configuration files, databases that store JSON, and
+more.
+
+**Fragment identifier considerations**: See {{schema-fragment}}
+
+**Additional information**:
+
+  * **Deprecated alias names for this type**: N/A
+
+  * **Magic number(s)**: N/A
+
+  * **File extension(s)**: json, schema.json
+
+  * **Macintosh file type code(s)**: N/A
+
+**Person and email address to contact for further information**: See Authors'
+Addresses section.
+
+**Intended usage**: COMMON
+
+**Restrictions on usage**: N/A.
+
+**Author**: See Authors' Addresses section.
+
+**Change controller**: N/A
+
+### Media Type application/schema-instance+json {#schema-instance-json}
+
+The `application/schema-instance+json` media type is an extension of the
+{{JSON}} media type that just adds the `schema` media type parameter and
+fragment identification. The following information serves as the registration
+form for the `application/schema-instance+json` media type.
+
+**Type name**: application
+
+**Subtype name**: schema-instance+json
+
+**Required parameters**: N/A
+
+**Optional parameters**:
+
+* **schema**: A URI identifying a JSON Schema that provides semantic information
+  about this JSON representation.
+
+**Encoding considerations**: Same as {{JSON}}
+
+**Security considerations**: Same as {{JSON}}
+
+**Interoperability considerations**: Same as {{JSON}}
+
+**Published specification**: (this document)
+
+**Applications that use this media type**: JSON Schema is used in a variety of
+applications including API servers and clients that validate JSON requests and
+responses, IDEs that valid configuration files, databases that store JSON, and
+more.
+
+**Fragment identifier considerations**: See {{schema-fragment}}
+
+**Additional information**:
+
+  * **Deprecated alias names for this type**: N/A
+  * **Magic number(s)**: N/A
+  * **File extension(s)**: json
+  * **Macintosh file type code(s)**: N/A
+
+**Person and email address to contact for further information**: See Authors'
+Addresses section.
+
+**Intended usage**: COMMON
+
+**Restrictions on usage**: N/A
+
+**Author**: See Authors' Addresses section.
+
+**Change controller**: N/A
 
 # Security Considerations
 
@@ -314,13 +560,15 @@ This specification defines the following new Internet media types {{MEDIATYPE}}.
 IANA has updated the "Media Types" registry at <https://www.iana.org/assignments/media-types>
 with the registration information provided below.
 
-|--------------------------|---------------------------------------|
-| Media Type               |                         Section       |
-|--------------------------|---------------------------------------|
-| application/yaml         | {{application-yaml}} of ThisRFC       |
-| application/openapi+yaml | {{openapi-yaml}} of ThisRFC           |
-| application/openapi+json | {{openapi-json}} of ThisRFC           |
-|--------------------------|---------------------------------------|
+|--------------------------------------|---------------------------------------|
+| Media Type                           | Section                               |
+|--------------------------------------|---------------------------------------|
+| application/yaml                     | {{application-yaml}} of ThisRFC       |
+| application/openapi+yaml             | {{openapi-yaml}} of ThisRFC           |
+| application/openapi+json             | {{openapi-json}} of ThisRFC           |
+| application/schema+json              | {{schema-json}} of ThisRFC            |
+| application/schema-instance+json     | {{schema-instance-json}} of ThisRFC   |
+|--------------------------------------|---------------------------------------|
 
 IANA has updated the "Structured Syntax Suffixes" registry at <https://www.iana.org/assignments/media-type-structured-suffix>
 with the registration information provided below.