diff --git a/hyper-schema-output.json b/hyper-schema-output.json new file mode 100644 index 00000000..46f52995 --- /dev/null +++ b/hyper-schema-output.json @@ -0,0 +1,61 @@ +{ + "$id": "http://json-schema.org/draft-7-wip/hyper-schema-output", + "$schema": "http://json-schema.org/draft-07-wip/schema#", + "type": "array", + "items": { + "allOf": [ + {"$ref": "http://json-schema.org/draft-07/links#/definitions/noRequiredFields" } + ], + "type": "object", + "required": [ + "contextUri", + "contextPointer", + "rel", + "attachmentPointer" + ], + "if": { "required": [ "hrefSchema" ] }, + "then": { "required": [ "hrefInputTemplates", "hrefPrepopulatedInput" ] }, + "else": { "required": [ "targetUri" ] }, + "properties": { + "contextUri": { + "$comment": "The fully resolved URI of the link context, including a fragment if it is possible to construct one for the given media type and instance", + "type": "string", + "format": "uri" + }, + "contextPointer": { + "$comment": "The absolute JSON Pointer to the location in the instance that is the context of the link. If the context resource supports JSON Pointer fragments, this will the string form of the identical JSON Pointer", + "type": "string", + "format": "json-pointer" + }, + "rel": { + "type": "string" + }, + "targetUri": { + "$comment": "The fully resolved target URI", + "type": "string", + "format": "uri" + }, + "hrefInputTemplates": { + "$comment": "The list of partially resolved URI Templates, starting with \"href\", followed by applicable \"base\" values from nearest to furthest.", + "type": "array", + "items": { + "type": "string", + "format": "uri-template" + } + }, + "hrefPrepopulatedInput": { + "$comment": "The initial data set to be presented with the input form when URI Tempalte input is accepted.", + "type": "object", + "propertyNames": { + "$comment": "These are all URI Template variable names, specifically the 'varname' production from RFC 6570, Section 2.3", + "pattern": "^(?:\\w|(?:%[a-f\\d]{2}))+(?:\\.(?:\\w|(?:%[a-f\\d]{2})))*$" + } + }, + "attachmentPointer": { + "$comment": "The absolute JSON Pointer, in string form, of the position to which this resolved link applies", + "type": "string", + "format": "json-pointer" + } + } + } +} diff --git a/hyper-schema.json b/hyper-schema.json index a342e497..68ca4fc7 100644 --- a/hyper-schema.json +++ b/hyper-schema.json @@ -1,18 +1,18 @@ { - "$schema": "http://json-schema.org/draft-06/hyper-schema#", - "$id": "http://json-schema.org/draft-06/hyper-schema#", + "$schema": "http://json-schema.org/draft-07-wip/hyper-schema#", + "$id": "http://json-schema.org/draft-07-wip/hyper-schema#", "title": "JSON Hyper-Schema", "definitions": { "schemaArray": { "allOf": [ - { "$ref": "http://json-schema.org/draft-06/schema#/definitions/schemaArray" }, + { "$ref": "http://json-schema.org/draft-07-wip/schema#/definitions/schemaArray" }, { "items": { "$ref": "#" } } ] } }, - "allOf": [ { "$ref": "http://json-schema.org/draft-06/schema#" } ], + "allOf": [ { "$ref": "http://json-schema.org/draft-07-wip/schema#" } ], "properties": { "additionalItems": { "$ref": "#" }, "additionalProperties": { "$ref": "#"}, @@ -50,12 +50,13 @@ "propertyNames": { "$ref": "#" }, "base": { - "type": "string" + "type": "string", + "format": "uri-template" }, "links": { "type": "array", "items": { - "$ref": "http://json-schema.org/draft-06/links#" + "$ref": "http://json-schema.org/draft-07-wip/links#" } } }, diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 65d54e83..c42d9b34 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -19,7 +19,7 @@ - + JSON Schema: A Media Type for Describing JSON Documents @@ -986,11 +986,13 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 - + Reserve "$comment" for non-user-visible notes about the schema Wording improvements around "$id" and fragments Note the challenges of extending meta-schemas with recursive references + Add "application/schema-instance+json" media type + Recommend a "schema" link relation / parameter instead of "profile" diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 7f368b56..87ac0c83 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -11,8 +11,10 @@ + - + + ]> @@ -24,18 +26,12 @@ - + JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON - -
- aaa@bzfx.net -
- - Cloudflare, Inc.
@@ -43,14 +39,9 @@
- +
- - - Cambridge - UK - - luffgd@gmail.com + aaa@bzfx.net
@@ -66,10 +57,10 @@ - JSON Schema is a JSON based format for defining the structure of JSON data. - This document specifies hyperlink- and hypermedia-related keywords of JSON Schema + JSON Schema is a JSON based format for describing JSON data using various + vocabularies. This document specifies a vocabulary for annotating JSON documents with hyperlinks and instructions for processing and - manipulating remote JSON resources through hypermedia environments like HTTP. + manipulating remote JSON resources through hypermedia environments such as HTTP. @@ -91,14 +82,24 @@
- JSON Schema is a JSON based format for defining the structure of JSON data. - This document specifies hyperlink- and hypermedia-related keywords of JSON Schema. + JSON Hyper-Schema is a JSON Schema vocabulary for annotating JSON documents + with hyperlinks and instructions for processing and + manipulating remote JSON resources through hypermedia environments such as HTTP. The term JSON Hyper-Schema is used to refer to a JSON Schema that uses these - keywords. + keywords. The term "hyper-schema" on its own refers to a JSON Hyper-Schema + within the scope of this specification. + + + The primary mechanism introduced for specifying links is the Link Description + Object (LDO), which is a serialization of the abstract link model + defined in RFC 5988bis, section 2. + + This section references the work-in-progress RFC5988bis, with the expectation + that it will reach RFC before this specification does. + - This specification will use the concepts, syntax, and terminology defined by the JSON Schema core and @@ -107,7 +108,7 @@
-
+
@@ -116,146 +117,193 @@ "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. - - - The terms "schema" and "instance" are to be interpreted as defined in the - JSON Schema core specification. -
- This document describes how JSON Schema can be used to define hyperlinks on instance - data. + JSON Hyper-Schema makes it possible to build hypermedia systems from JSON + documents by describing how to construct hyperlinks from instance data. - As with all JSON Schema keywords, all the keywords described in the "Schema - Keywords" section are optional. The minimal valid JSON Hyper-schema is the blank - object. + The combination of a JSON instance document and a valid application/schema+json + hyper-schema for that instance behaves as a single hypermedia representation. + By allowing this separation, hyper-schema-based systems can gracefully support + applications that expect plain JSON, while providing full hypermedia capabilities + for hyper-schema-aware applications and user agents. -
- - Here is an example JSON Schema defining hyperlinks: - - - - - - This example schema defines the properties of the instance as well as link - relations for the instance, with URIs incorporating values from the instance. - -
+ + Client-side user agents can detect the presence of hyper-schema by looking for + the application/schema+json media type and a "$schema" value that indicates the + presence of the hyper-schema vocabulary. A user agent can then use an + implementation of JSON Hyper-Schema to provide an interface to the + combination of the schema and instance documents as a single logical + representation of a resource, just as with any single-document hypermedia + representation format. + + + Hyper-schemas allow representations to take up fewer bytes on the wire, and + distribute the burden of link construction from the server to each client. + A user agent need not construct a link unless a client application requests + that link. JSON Hyper-Schema can also be used on the server side to generate + other link serializations or representation formats at runtime, or pre-emptively + follow links to facilitate server push usage. + + +
+ + The terms "schema", "instance", and "meta-schema" are to be interpreted as + defined in the JSON Schema core specification. + + + The terms "applicable" and "attached" are to be interpreted as defined in + Section 10.1 of the + JSON Schema validation specification. + + + The terms "link", "link context" (or "context"), "link target" (or "target"), + and "target attributes" are to be interpreted as defined in + Section 2 of RFC 5988bis. + + + The term "user agent" is to be interpreted as defined in + Section 2.1 of RFC 7230, generalized to apply + to any protocol that may be used in a hypermedia system rather than + specifically being an HTTP client. + + + This specification defines the following terms: + + + A JSON Schema using the keywords defined by this specification. + + + Within this document, the term "hyper-schema" always refers to + a JSON Hyper-Schema + + + A valid link for an instance is one that is applicable to that + instance and does not fail any requirement imposed by the keywords + in the Link Description Object. + + + A user agent which is only aware of standardized link relations, + media types, URI schemes, and protocols. It may have an extensible + architecture to allow adding support for standards beyond the core + set of which it is aware. + + + An application which uses a hypermedia system for a specific + purpose. Such an application may also be its own user agent, + or it may be built on top of a generic user agent. A client + application is programmed with knowledge of link relations, + media types, URI schemes, protocols, and data structures that + are specific to the application's domain. + + + Data provided through a user agent, and most often also through + a client application. Such data may be requested from a user + interactively, or provided before interaction in forms such as + command-line arguments, configuration files, or hardcoded values + in source code. + + + +
+ +
+ + A JSON Hyper-Schema implementation is able to take a hyper-schema, an + instance, and in some cases client input, and produce a set of fully + resolved valid links. As defined by + RFC 5988bis, section 2, + a link consists of a context, a typed relation, a target, and optionally + additional target attributes. + + + The relation type and target attributes are taken directly from each link's + Link Description Object. The context and target identifiers are constructed + from some combination of URI Templates, instance data, and (in the case + of the target identifier) client input. + + + The target is always fully identified by a URI. Due to the lack of a URI + fragment identifier syntax for application/json and many other media types + that can be used with JSON Hyper-Schema, the context may be only partially + identified by a URI. In such cases, the remaining identification will be + provided as a JSON Pointer. + + + A few IANA-registered link relation types are given specific semantics in + a JSON Hyper-Schema document. A "self" link is used to interact with the + resource that the instance document represents, while "collection" and + "item" links identify resources for which collection-specific semantics + can be assumed. + +
-
+
+ + The "draft-07-wip" is a placeholder. + The current URI for the JSON Hyper-Schema meta-schema is - <http://json-schema.org/draft-06/hyper-schema#>. + + http://json-schema.org/draft-07-wip/hyper-schema# + (draft-07 work-in-progress version). + + + The link description format can be used without JSON + Schema, and use of this format can be declared by referencing the normative + link description schema as the schema for the data structure that uses the links. + The URI of the normative link description schema is: + + http://json-schema.org/draft-07-wip/links# + (draft-07 work-in-progress version). + + + JSON Hyper-Schema implementations are free to provide output in any format. + However, a specific format is defined for use in the conformance test suite, + which is also used to illustrate points in the + "Implementation Requirements", and to + show the output generated by examples. + It is RECOMMENDED that implementations be capable of producing output + in this format to facilitated testing. The URI of the JSON Schema + describing the recommended output format is + + http://json-schema.org/draft-7-wip/hyper-schema-output# + (draft-07 work-in-progress version).
-
- Hyper-schema keywords can be applied when the instance is valid against - the schema that includes those keywords, as outlined under "Annotations" in - Section 3.3 of JSON Schema validation. + Hyper-schema keywords from all schemas that are applicable to a position + in an instance, as defined by Section + 10.1 of JSON Schema validation, can be used with that instance. When multiple subschemas are applicable to a given sub-instance, all "link" - arrays MUST be concatenated, in any order, into a single array. Each object - in the resulting array MUST retain its own list of applicable "base" values, + arrays MUST be combined, in any order, into a single set. Each object + in the resulting set MUST retain its own list of applicable "base" values, in resolution order, from the same schema and any parent schemas. -
- - If present, this keyword is resolved against the current URI base that the - entire instance is found within, and sets the new URI base for URI references - within the instance. - It is therefore the first URI Reference resolved, regardless of which order it - was found in. - - - The URI is computed from the provided URI template using the same process - described for the "href" property of a Link - Description Object. - -
- - An example of a JSON schema using "base": - - - - -
-
- - An example of a JSON instance using this schema to produce rel="self" and - rel="next" links: - - - - -
+ + As with all JSON Schema keywords, all keywords described in this section + are optional. The minimal valid JSON Hyper-schema is the blank object. + + +
- If the document URI is <http://example.com/?id=41>, then the new URI base - becomes <http://example.com/object/41> + If present, this keyword MUST be first resolved as + a URI Template, and then MUST be resolved as a URI Reference against the + current URI base of the instance. The result MUST be set as the new URI + base for the instance while processing the sub-schema containing "base" + and all sub-schemas within it. - Resolving the two Link Description Objects against this URI base creates two - links exactly equivalent to these absolute-form HTTP Link headers: - - Link: <http://example.com/object/41>;rel=self - Link: <http://example.com/object/42>;rel=next - + The process for resolving the "base" template can be different when being + resolved for use with "anchor" than when being resolved for use with "href", + which is explained in detail in the URI Templating section.
@@ -265,1297 +313,690 @@ with instances. The value of this property MUST be an array, and the items in the array must be Link Description Objects, as defined below. - -
- - An example schema using the "links" keyword could be: - - - - -
-
-
+
- A Link Description Object (LDO) is used to describe a single link relation from the - instance to another resource. - A Link Description Object must be an object. + + This section references the work-in-progress RFC5988bis, with the expectation + that it will reach RFC before this specification does. + + A Link Description Object (LDO) is a serialization of the abstract link model + defined in RFC 5988bis, section 2. + As described in that document, a link consists of a context, a relation type, + a target, and optionally target attributes. JSON Hyper-Schema's LDO provides + all of these, along with additional features using JSON Schema to describe input + for use with the links in various ways. - - The link description format can be used without JSON Schema, and use of this format - can be declared by referencing the normative link description schema as the schema - for the data structure that uses the links. - The URI of the normative link description schema is: - http://json-schema.org/draft-06/links - (draft-06 version). + Due to the use of URI Templates to identify link contexts and targets, as well + as optional further use of client input when identifying targets, an LDO is + a link template that may resolve to multiple links when used with a JSON + instance document. + + + A specific use of an LDO, typically involving a request and response across + a protocol, is referred to as an operation. For many protocols, multiple + operations are possible on any given link. The protocol is indicated by + the target's URI scheme. Note that not all URI schemes indicate a protocol + that can be used for communications, and even resources with URI schemes that + do indicate such protocols need not be available over that protocol. + + + A Link Description Object MUST be an object, and the + "href" and "rel" properties + MUST be present. Each keyword is covered briefly in this section, with additional + usage explanation and comprehensive examples given later in the document. -
- - - Note that while the current draft does not provide a way to explicity - indicate HTTP method support, some way of providing a non-authoritative - hint may be added in a future draft (see issue #73 in the GitHub repository). - - +
- An operation is a specific use of a link described by an LDO, after any - template variables have been resolved. + In JSON Hyper-Schema, the link's context resource is, by default, the + sub-instance to which it is attached (as defined by + Section 10.1 of the JSON Schema + validation specification). This is often not the entire instance + document. This default context can be changed using the keywords + in this section. - There are several ways that a client can use data with a link: - - URI Template variables resolved from server-supplied instance data - URI Template variables resolved from user agent data - Replacing or modifying the target resource's representation - Submitting data for processing, where the data has no - inherent relation to the target resource's representation - - The three ways to use client-supplied data are each addressed by a separate - schema keyword within the link description object. When performing operations, - clients SHOULD ignore schemas that are not relevant to their semantics. + Depending on the media type of the instance, it may or may not be possible + to assign a URI to the exact default context resource. In particular, + application/json does not define a URI fragment resolution syntax, so + properties or array elements within a plain JSON document cannot be fully + identified by a URI. When it is not possible to produce a complete URI, + the position of the context SHOULD be conveyed by a the URI of the instance + document, together with a separate plain-string JSON Pointer. - Link Description Objects do not directly indicate what operations, such - as HTTP methods, are supported by the target resource. Instead, operations - should be inferred primarily from link relation types - and URI schemes. Note, however, that a resource may always decline an operation - at runtime, for instance due to application state that controls the operation's - availability. + Implementations MUST be able to construct the link context's URI, and + (if necessary for full identification), a JSON Pointer in string representation + form as per RFC 6901, section 5 in place of + a URI fragment. The process for constructing a URI based on a URI template + is given in the URI Templating section. -
+
- In JSON Hyper-Schema, "targetSchema" - supplies a non-authoritative description of the target resource's - representation. A client can use "targetSchema" to structure input for - replacing or modifying the representation. Alternatively, if "targetSchema" - is absent or if the client prefers to only use authoritative information, it - can interact with the target resource to confirm or discover its - representation structure. + This property sets the context URI of the link. + The value of the property is a URI Template, + and the resulting URI-reference MUST + be resolved against the base URI of the instance. - "targetSchema" is not intended to describe link operation responses, - except when the response semantics indicate that it is a representation - of the target resource. In all cases, the schema indicated by the response - itself is authoritative. See the - for guidance - specific to each HTTP method when using "targetSchema" with HTTP URIs. + The URI is computed from the provided URI template using the same process + described for the "href" property, with the + exception that "hrefSchema" MUST NOT + be applied. Unlike target URIs, context URIs do not accept user input.
-
+
- The "submissionSchema" and - "submissionMediaType" keywords - describe the domain of the processing function implemented by the target - resource. Otherwise, as noted above, the submission schema and media type - are ignored for operations to which they are not relevant. + This property changes the point within the instance that is considered + to be the context resource of the link. The value of the property MUST + be a valid JSON Pointer in JSON String representation form, or a valid + Relative JSON Pointer + which is evaluated relative to the default context. + + + While an alternate context with a known URI is best set with the + "anchor" keyword, the lack of a fragment + identifier syntax for application/json means that it is usually not + possible to change the context within a JSON instance using a URI. + + + Even in "+json" media types that define JSON Pointer as a fragment + identifier syntax, if the default context is nested within an array, + it is not possible to obtain the index of the default context's position + in that array in order to construct a pointer to another property in that + same nested JSON object. This will be demonstrated in the examples. + + + The result of processing this keyword SHOULD be a URI fragment if the + media type of the instance allows for such a fragment. Otherwise it + MUST be a string-encoded JSON Pointer.
- - - -
+
- The value of the "href" link description property is a template used to - determine the target URI of the related resource. - The value of the instance property MUST be resolved as a - URI-reference against the base URI of the - instance. + The link's relation type identifies its semantics. It is the primary + means of conveying how an application can interact with a resource. - This property is REQUIRED. + Relationship definitions are not normally media type + dependent, and users are encouraged to utilize the most + suitable existing accepted relation definitions. - +
+ + The value of this property MUST be a string, and MUST be a single + Link Relation Type as defined in RFC 5988bis, Section 2.1. + + + This property is required. + +
+
+ + A hyper-schema implementation MUST recognize that a link with relation + type "self" that is applicable to the entire instance document describes + how a user agent can interact with the resource represented by that + instance document. A "self" link MUST be resolvable from the instance, + and therefore "hrefSchema" MUST NOT be present. + + + Hyper-schema authors SHOULD use "templateRequired" to ensure that the + "self" link has all instance data that is needed for use. + +
+
+ + RFC 6573 defines and registers + the "item" and "collection" link relation types. JSON Hyper-Schema imposes + additional semantics on collection resources indicated by these types. + + + Implementations MUST recognize the target of a "collection" link and + the context of an "item" link as collections. + + + A well-known design pattern in hypermedia is to use a collection resource + to create a member of the collection and give it a server-assigned URI. + If the protocol indicated by the URI scheme defines a specific method + that is suited to creating a resource with a server-assigned URI, then + a collection resource, as identified by these link relation types, + MUST NOT define semantics for that method that conflict with the semantics + of creating a collection member. Collection resources MAY implement + item creation via such a protocol method, and user agents MAY assume + that any such operation, if it exists, has item creation semantics. + + + As such a method would correspond to JSON Hyper-Schema's data submission + concept, the "submissionSchema" + field for the link SHOULD be compatible with the schema of the + representation of the collection's items, as indicated by the "item" link's + target resource or the "self" link of the "collection" link's context + resource. + +
+
+ + When no registered relation (aside from "related") applies, users are + encouraged to mint their own extension relation types, as described in + section 4.2 of RFC 5988. The simplest + approaches for choosing link relation type URIs are to either use + a URI scheme that is already in use to identify the system's primary + resources, or to use a human-readable, non-dereferenceable URI scheme + such as "tag", defined by RFC 4151. + + + Extension relation type URIs need not be dereferenceable, even when + using a scheme that allows it. + +
- -
- - The value of the "templatePointers" link description property MUST be - an object. Each property value in the object MUST be a valid - JSON Pointer, or a valid - Relative JSON Pointer - which is evaluated relative to the position in the instance from which - "href" template variable resolution would - normally begin. - - - For each property name in the object that matches a variable name in the - "href" URI Template, the value of that property adjusts the starting position - of variable resolution for that variable. Properties which do not match - "href" template variable names MUST be ignored. - -
- - Recall that a Relative JSON Pointer begins with a number indicating - how many levels up to move before applying the remainder of the pointer, - if any, in the same manner as a regular JSON Pointer. Consider the - following schema for n-ary tree nodes, where a node is identified by - its own id as well as the tree's root node id, and links are given for - the IANA-registered "self" and "up" link relation types. - - - - -
- - In "self" link, the context node's id resolves with the standard process and - therefore does not appear in "templatePointers". In both "self" and "up" links, - the root id is located using an absolute JSON Pointer. Finally, in "up" link, - the parent node uses a Relative JSON Pointer, going up two levels (one level up - is the array of children, two levels up is the whole parent node), and then - looking at the "id" field from that point. - -
- - Given the following instance: - - - - -
- - For each node (as identified by JSON Pointers), we get these "self" links: - - /trees/0/nodes/0 - /trees/0/nodes/1 - /trees/0/nodes/2 - /trees/0/nodes/3 - - - - and these "up" links: - - /trees/0/nodes/0 - /trees/0/nodes/1 - /trees/0/nodes/2 - - +
- For the root node, the relative pointer for the parent doesn't point - to anything, so "templateRequired" - prevents the link from being used with that node. + The target URI template is used to identify the link's target, potentially + making use of instance data. Additionally, with + "hrefSchema", this template can identify + a set of possible target resources to use based on client input. + The full process of resolving the URI template, with or without client + input, is covered in the URI Templating + section. +
+ + The value of the "href" link description property is a template used to + determine the target URI of the related resource. + The value of the instance property MUST be resolved as a + URI-reference against the base URI of the + instance. + + + This property is REQUIRED. + +
-
- - The value of the "hrefSchema" link description property MUST be - a valid JSON Schema. This schema is used to validate user input - or other user agent data for filling out the URI Template in - "href", as described in that section. - - - Omitting "hrefSchema" or setting the entire schema to "false" prevents - any user agent data from being accepted. - +
- Setting any subschema that applies to a particular variable to "false" - prevents any user agent data from being accepted for that single variable. + The keywords in this section are used when resolving all URI Templates + involved in hyper-schema: "base", "anchor", and "href". See the + URI Templating section for the complete + template resolution algorithm. - For template variables that can be resolved from the instance data, - if the instance data is valid against all applicable subschemas - in "hrefSchema", then it MUST be used to pre-populate the input - data set for that variable. - - - Note that even when data is pre-populated from the instance, the validation - schema for that variable in "hrefSchema" need not be identical to the validation - schema(s) that apply to the instance data's location. This allows for different - validation rules for user agent data, such as supporting spelled-out - months for date-time input, but using the standard date-time format for storage. - -
- - For example, this defines a schema for each of the query string - parameters in the URI template: - - - - -
-
- - In the following example, the schema for "extra" is given as a reference - to keep the user agent data validation constraints identical to the - instance validation constraints for the corresponding property, - while "id" is given a false schema to prevent user agent data for - that variable. - - - - -
- - - The above example simulates the behavior handled in earlier drafts - with a "method" of "get" by using the new "hrefSchema" keyword. - + Note that when resolving a "base" template, the attachment point from + which resolution begins is the attachment point of the "href" or "anchor" + keyword being resolved which requires "base" templates to be resolved, + not the attachment point of the "base" keyword itself. +
+ + The value of the "templatePointers" link description property MUST be + an object. Each property value in the object MUST be a valid + JSON Pointer, or a valid + Relative JSON Pointer + which is evaluated relative to the attachment point of the link + for which the template is being resolved. + + + For each property name in the object that matches a variable name in the + template being resolved, the value of that property adjusts the starting + position of variable resolution for that variable. Properties which + do not match template variable names in the template being resolved + MUST be ignored. + +
+
+ + The value of this keyword MUST be an array, and the elements MUST be unique. + Each element SHOULD match a variable in the link's URI Template, without + percent-encoding. After completing the entire URI Template resolution + process, if any variable that is present in this array does not have + a value, the link MUST NOT be used. + +
-
+
- The value of this keyword MUST be an array, and the elements MUST be unique. - Each element SHOULD match a variable in the link's URI Template, without - percent-encoding. After completing the entire URI Template resolution - process, if any variable that is present in this array does not have - a value, the link MUST NOT be used. + All properties in this section are advisory only. While keywords such + as "title" and "description" are used primarily to present the link + to users, those keywords that predict the nature of a link interaction + or response MUST NOT be considered authoritative. The runtime behavior + of the target resource MUST be respected whenever it conflicts with + the target attributes in the LDO. -
- - Here is a simplified version of the "up" link from the - "templatePointers tree example, - modified to only use the parent identifier for its "href" template. - While each individual node is required to have an "id" field, the - "up" link uses the parent node's field, and the root node, by definition, - does not have a parent node. Putting "parentId" in "templateRequired" - ensures that the "up" link is correctly unusable with the root node. - - - - -
-
+
+ + This property defines a title for the link. + The value MUST be a string. + -
- - The value of the "rel" property indicates the name of the relation to the target - resource. The value MUST be a registered link relation from the - IANA Link Relation Type Registry established in RFC 5988, - or a normalized URI following the URI production of RFC 3986. - This property is required. - + + User agents MAY use this title when presenting the link to the user. + +
- - As defined by RFC 5988, a link connects a context resource - to a target resource, where the nature of the connection - is described by the link relation type. The context - resource is the instance to which the schema (or sub-schema) - applies, rather than any larger document in which the - instance may have been found. The context may be changed - with the "anchor" or - "anchorPointer" properties. - +
+ + This property provides additional information beyond what + is present in the title. The value MUST be a string. + While a title is preferably short, a description can be + used to go into more detail about the purpose and usage + of the link. + - - Depending on the media type of the instance, it may or may - not be possible to assign a URI to the exact default context - resource. In particular, application/json does not define - URI fragment resolution semantics, so properties or array - elements within a plain JSON document cannot be identified - by a URI. - + + User agents MAY use this description when presenting + the link to the user. + +
- - Relationship definitions are not normally media type - dependent, and users are encouraged to utilize the most - suitable existing accepted relation definitions. - +
+ + The value of this property represents the media type + RFC 2046, that is expected to be returned + when fetching this resource. This property value MAY be a media range + instead, using the same pattern defined in + RFC 7231, section 5.3.2 - + HTTP "Accept" header. + + + This property is analogous to the "type" property of other link + serialization formats. User agents MAY use this information to inform + the interface they present to the user before the link is followed, + but MUST NOT use this information in the interpretation of the resulting + data. Instead, a client MUST use the media type given by the response for + run-time interpretation. See the section on + "Security Concerns" for a detailed + examination of mis-use of "targetMediaType". + + + For protocols supporting content-negotiation, implementations MAY choose to + describe possible target media types using protocol-specific information in + "headerSchema". If both + protocol-specific information and "targtMediaType" are present, then the + value of "targetMediaType" MUST be compatible with the protocol-specific + information, and SHOULD indicate the media type that will be returned in the + absence of content negotiation. + + + When no such protocol-specific information is available, or when the + implementation does not recognize the protocol involved, then the value + SHOULD be taken to be "application/json". + +
- - When no registered relation (aside from "related") applies, users are - encouraged to mint their own extension relation types, as described in - section 4.2 of RFC 5988. The simplest - approaches for choosing link relation type URIs are to either use - a URI scheme that is already in use to identify the system's primary - resources, or to use a human-readable, non-dereferenceable URI scheme - such as "tag", defined by RFC 4151. - Extension relation type URIs need not be dereferenceable, even when - using a scheme that allows it. - -
- - As an example of registered relation types, if a hyper-schema is defined: - - - - -
- -
- - And if a collection of instance resources were retrieved with JSON - representation: - - - - - - This would indicate that for the first item in the collection, its URI as - its own resource would resolve to "/Resource/thing" and the first item's - "up" relation SHOULD be resolved to the resource at "/Resource/parent". - -
+
+ + This property provides a schema that is expected to describe + the link target's representation. Depending on the protocol, + the schema may or may not describe the request or response to + any particular operation performed with the link. See the + JSON Hyper-Schema and HTTP section for + an in-depth discussion of how this keyword is used with HTTP. + +
- - Note that these relationship values are case-insensitive, consistent with their - use in HTML and the HTTP Link header. - -
+
- RFC 6573 defines and registers - the "item" and "collection" link relations. A well-known design pattern - in hypermedia is to use a collection resource to create a member of the - collection and give it a server-assigned URI. When using HTTP, or a protocol - such as CoAP that is explicitly analogous to HTTP, this is done by POST-ing - a representation of the individual resource to be created to the collection - resource. + + This section attempts to strike a balance between comprehensiveness + and flexibility by deferring most of its structure to the protocol + indicated by the URI scheme. Note that a resource can be identified + by a URI with a dereferenceable scheme, yet not be accessible over + that protocol. While currently very loose, this section is expected + to become more well-defined based on draft feedback, and may change + significantly in future drafts. + - Resources that are the target of a "collection" link using HTTP or an analogous - protocol in JSON Hyper-Schema MUST NOT assign semantics other than resource - creation to POST (or the analogous method in non-HTTP protocols). + The value of this property is advisory only. It represents information that + is expected to be discoverable through interacting with the target resource, + typically in the form of protocol-specific control information or meta-data + such as headers returned in response to an HTTP HEAD or OPTIONS request. + The protocol is determined by the "href" URI scheme, although note that + resources are not guaranteed to be accessible over such a protocol. - The "submissionSchema" field for the - link SHOULD be identical to the schema of the representations of the - collection's items, as indicated by the "item" link. RFC 6573 identifies - the "collection" and "item" link relation types as reciprocal, so the - context resource of an "item" link MAY be treated as a collection, even if - no explicit "collection" link is defined. + The value of this property SHOULD be an object. The keys to this object + SHOULD be lower-cased forms of the control data field names. Each value + SHOULD be an array, in order to uniformly handle multi-valued fields. + Multiple values MUST be presented as an array, and not as a single string. -
- - The first of these hyper-schemas describes an individual "thing", - while the second describes a collection of "things". Note that the - "targetSchema" of the individual thing's "self" link is the same - as the "submissionSchema" of its "collection" link. - - - - - - - - In the hyper-schema for the collection, the "item" link also demonstrates - the usage of "anchorPointer", as the context of that link must be the - entire collection, rather than the individual array element to which the - link is attached. The collection's self link also supports a - "submissionSchema" matching that of its "item" link's "targetSchema". - -
-
- -
- When link relation of "self" is used to denote a full representation of an - object, the user agent SHOULD NOT consider the representation to be the - authoritative representation of the resource denoted by the target URI if - the target URI is not equivalent to or a sub-path of the URI used to request - the resource representation which contains the target URI with the "self" - link. - -
- - For example, if a hyper-schema was defined: - - - - -
- -
- - And a resource was requested from somesite.com: - - - - -
- -
- - With a response of (with newlines and whitespace added): - - - - -
+ Protocols with control information not suitable for representation as + a JSON object MAY be represented by another data type, such as an array. -
-
- -
- - This property sets the context URI of the link. - The value of the property is a URI Template, - and the resulting URI-reference MUST be resolved - against the base URI of the instance. - - - The URI is computed from the provided URI template using the same process - described for the "href" property, with the - exception that "hrefSchema" MUST NOT - be applied. Unlike target URIs, context URIs do not accept user input. - -
- -
- - This property changes the point within the instance that is considered - to be the context resource of the link. The value of the property MUST be a - valid JSON Pointer, or a valid - Relative JSON Pointer - which is evaluated relative to the position in the instance from which - "href" template variable resolution would - normally begin. - - - While an alternate context with a known URI is best set with the - "anchor" keyword, the lack of a fragment identifier - syntax for application/json means that it is usually not possible to - change the context within a JSON instance using a URI. - - - Even in "+json" media types that define JSON Pointer as a fragment identifier - syntax, if the default context is nested within an array, it is not possible to - obtain the index of the default context's position in that array in order - to construct a pointer to another property in that same nested JSON object. - - -
- - For example, given this hyper-schema: - - - - - - The "item" relation indicates that each array entry can be used to construct - a link from the collection embedded in this instance to a resource for that - specific item. The default context of this link is the individual array - element. But the context of an "item" relation should be the collection, - which is the entire "examples" array. The Relative JSON Pointer of "1" - accomplishes this as follows: - -
-
- - Given this instance of media type application/json: - - - - - - The default context for the link to "/examples/1234" is the first - array entry, and for the link to "/examples/5678" it is the second array - entry. But "anchorPointer" moves this up one instance level (the "1" - Relative JSON Pointer) to be the array containing each entry. - -
- - If both "anchor" and "anchorPointer" are defined, and do not resolve to - the same link context, the resulting behavior is undefined. - -
- -
- - This property defines a title for the link. - The value MUST be a string. - - - - User agents MAY use this title when presenting the link to the user. - -
- -
- - This property provides additional information beyond what - is present in the title. The value MUST be a string. - While a title is preferably short, a description can be - used to go into more detail about the purpose and usage - of the link. - - - - User agents MAY use this description when presenting - the link to the user. - -
- -
- - This property provides a schema that is expected to describe - the link target's representation. Depending on the protocol, - the schema may or may not describe the response to any particular - request sent to the link. This property is advisory only. - -
- The relationship between a resource's representation and HTTP requests and - responses is determined by RFC 7231, section 4.3.1 - - "GET", section 4.3.4 "PUT", and section 3.1.4.2, - "Content-Location". In particular, "targetSchema" suggests what a - client can expect for the response to an HTTP GET or any response for which - the "Content-Location" header is equal to the request URI, and what a client - should send if it replaces the resource in an HTTP PUT request. Per RFC 5789, the request structure for an HTTP - PATCH is determined by the combination of "targetSchema" and the request - media type. + Values that cannot be understood as part of the indicated protocol MUST + be ignored by a JSON Hyper-Schema implementation. Applications MAY make + use of such values, but MUST NOT assume interoperability with other + implementations. -
-
- This property has similar security concerns to that of "targetMediaType". - Clients MUST NOT use the value of this property to aid in the interpretation - of the data received in response to following the link, as this leaves - "safe" data open to re-interpretation. + Implementations MUST NOT assume that all discoverable information is + accounted for in this object. Clients MUST properly handle run-time + responses that contradict this property's values. -
- - For example, suppose two programmers are having a discussion about - web security using a text-only message board. - Here is some data from that conversation, with a URI of: - http://forum.example.com/topics/152/comments/13 - - -doSomethingEvil()" -}]]> - - - The message string was split over two lines for readability. - -
+ Clients MUST NOT assume that an implementation will automatically take any + action based on the value of this property. - A third party might then provide the following Link Description Object at - another location: -
- - - - - If the client used this "targetSchema" value when interpreting the - above data, then it might display the contents of "message" as HTML. - At this point, the JavaScript embedded in the message might be - executed (in the context of the "forum.example.com" domain). - -
+ See "JSON Hyper-Schema and HTTP" for + guidance on using this keyword with HTTP and analogous protocols.
- -
- - - This section attempts to strike a balance between comprehensiveness - and flexibility by deferring most of its structure to the protocol - indicated by the URI scheme. Note that a resource can be identified - by a URI with a dereferenceable scheme, yet not be accessible over - that protocol. While currently very loose, this section is expected - to become more well-defined based on draft feedback, and may change - significantly in future drafts. - - - - The value of this property is advisory only. It represents information that - is expected to be discoverable through interacting with the target resource, - typically in the form of protocol-specific control information or meta-data - such as headers returned in response to an HTTP HEAD or OPTIONS request. - The protocol is determined by the "href" URI scheme, although note that - resources are not guaranteed to be accessible over such a protocol. - - - The value of this property SHOULD be an object. The keys to this object - SHOULD be lower-cased forms of the control data field names. Each value - SHOULD be an array, in order to uniformly handle multi-valued fields. - Multiple values MUST be presented as an array, and not as a single string. - - - Protocols with control information not suitable for representation as - a JSON object MAY be represented by another data type, such as an array. - +
- Values that cannot be understood as part of the indicated protocol MUST - be ignored by a JSON Hyper-Schema implementation. Applications MAY make - use of such values, but MUST NOT assume interoperability with other - implementations. + There are four ways to use client-supplied data with a link, and each + is addressed by a separate link description object keyword. When performing + operations, clients SHOULD ignore schemas that are not relevant to their + semantics. - - Implementations MUST NOT assume that all discoverable information is - accounted for in this object. Clients MUST properly handle run-time responses - that contradict this property's values. - - - Clients MUST NOT assume that an implementation will automatically take any - action based on the value of this property. - -
+
- It would be good to also include a section with CoAP examples. + The value of the "hrefSchema" link description property MUST be + a valid JSON Schema. This schema is used to validate user input + or other user agent data for filling out the URI Template in + "href". - JSON serializations of HTTP response header information SHOULD follow the - guidelines established by the work in progress - "A JSON Encoding for HTTP Header Field Values". - Approaches shown in that document's examples SHOULD be applied to other - similarly structured headers wherever possible. + Omitting "hrefSchema" or setting the entire schema to "false" prevents + any user agent data from being accepted. - It is RECOMMENDED that schema authors provide hints for the values of - the following types of HTTP headers whenever applicable: - - Method allowance - Method-specific request media types - Authentication challenges - + Setting any subschema that applies to a particular variable to the + JSON literal value "false" prevents any user agent data from being + accepted for that single variable. - In general, headers that are likely to have different values at different - times SHOULD NOT be included in "targetHints". + For template variables that can be resolved from the instance data, + if the instance data is valid against all applicable subschemas + in "hrefSchema", then it MUST be used to pre-populate the input + data set for that variable. - No distinction is made between headers that may appear in responses to - different methods, such as HEAD vs OPTIONS. + Note that even when data is pre-populated from the instance, the + validation schema for that variable in "hrefSchema" need not be identical + to the validation schema(s) that apply to the instance data's location. + This allows for different validation rules for user agent data, such as + supporting spelled-out months for date-time input, but using the standard + date-time format for storage. + + + After input is accepted, potentially overriding the pre-populated + instance data, the resulting data set MUST successfully validate + against the value of "hrefSchema". If it does not then the link + MUST NOT be used. If it is valid, then the process given in the + "URI Templating" section continues with this updated data set. -
- - This examples shows several hints that are useful for clients - when determining what requests to make and how to make them. - - - - -
-
-
- - The value of this property is advisory only, and represents the media type - RFC 2046, that is expected to be returned when - fetching this resource. - This property value MAY be a media range instead, using the same pattern defined - in RFC 7231, section 5.3.2 - HTTP "Accept" header. - - - - This property is analogous to the "type" property of <a> elements in HTML - (advisory content type), or the "type" parameter in the - HTTP Link header. - User agents MAY use this information to inform the interface they present to the - user before the link is followed, but this information MUST NOT use this - information in the interpretation of the resulting data. - When deciding how to interpret data obtained through following this link, the - behaviour of user agents MUST be identical regardless of the value of the this - property. - - - - If this property's value is specified, and the link's target is to be obtained - using any protocol that supports the HTTP/1.1 "Accept" header - RFC 7231, section 5.3.2, then user agents MAY use - the value of this property to aid in the assembly of that header when making the - request to the server. - - - - For protocols supporting content-negotiation, implementations MAY choose to - describe possible target media types using protocol-specific information in - "headerSchema". If both protocol-specific - information and "mediaType" are present, then the value of "mediaType" MUST - be compatible with the protocol-specific information, and SHOULD indicate - the media type that will be used in the absence of content negotiation. - - - - When no such protocol-specific information is available, or when the - implementation does not recognize the protocol involved, then the value - SHOULD be taken to be "application/json". - - -
- - For example, if a schema is defined: - - - - - - A suitable instance described by this schema would have four links defined. - The link with a "rel" value of "self" would have an expected MIME type of - "application/json" (the default). - The two links with a "rel" value of "alternate" specify the locations of - HTML and RSS versions of the current item. - The link with a "rel" value of "icon" links to an image, but does not - specify the exact format. - -
- - - A visual user agent displaying the item from the above example might present a - button representing an RSS feed, which when pressed passes the target URI - (calculated "href" value) to an view more suited to displaying it, such as a - news feed aggregator tab. - - - - Note that presenting the link in the above manner, or passing the URI to a news - feed aggregator view does not constitute interpretation of the data, but an - interpretation of the link. - The interpretation of the data itself is performed by the news feed aggregator, - which SHOULD reject any data that would not have also been interpreted as a news - feed, had it been displayed in the main view. - - -
+
- The "targetMediaType" property in link definitions defines the expected - format of the link's target. - However, this is advisory only, and MUST NOT be considered authoritative. + + As with "targetHints", this keyword is somewhat under-specified + to encourage experimentation and feedback as we try to balance + flexibility and clarity. + - - When choosing how to interpret data, the type information provided by the - server (or inferred from the filename, or any other usual method) MUST be - the only consideration, and the "targetMediaType" property of the link - MUST NOT be used. - User agents MAY use this information to determine how they represent the - link or where to display it (for example hover-text, opening in a new tab). - If user agents decide to pass the link to an external program, they SHOULD - first verify that the data is of a type that would normally be passed to - that external program. + If present, this property is a schema for protocol-specific request + headers or analogous control and meta-data. The value of this + object MUST be a valid JSON Schema. + The protocol is determined by the "href" URI scheme, although note that + resources are not guaranteed to be accessible over such a protocol. + The schema is advisory only; the target resource's behavior is not + constrained by its presence. + + + The purpose of this keyword is to advertise target resource interaction + features, and indicate to clients what headers and header values are + likely to be useful. Clients MAY use the schema to validate relevant + headers, but MUST NOT assume that missing headers or values are forbidden + from use. While schema authors MAY set "additionalProperties" to + false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents + from supplying additional headers when requests are made. - - This is to guard against re-interpretation of "safe" data, similar to the - precautions for "targetSchema". + The exact mapping of the JSON data model into the headers is + protocol-dependent. However, in most cases this schema SHOULD + specify a type of "object", and the property names SHOULD be + lower-cased forms of the control data field names. See the + "JSON Hyper-Schema and HTTP" section + for detailed guidance on using this keyword with HTTP and + analogous protocols. + + + "headerSchema" is applicable to any request method or command that the + protocol supports. When generating a request, clients SHOULD ignore + schemas for headers that are not relevant to that request.
-
-
- - - As with "targetHints", this keyword is somewhat under-specified - to encourage experimentation and feedback as we try to balance - flexibility and clarity. - - - - If present, this property is a schema for protocol-specific request - headers or analogous control and meta-data. The value of this - object MUST be a valid JSON Schema. - The protocol is determined by the "href" URI scheme, although note that - resources are not guaranteed to be accessible over such a protocol. - The schema is advisory only; the target resource's behavior is not - constrained by its presence. - - - The purpose of this keyword is to advertise target resource interaction - features, and indicate to clients what headers and header values are - likely to be useful. Clients MAY use the schema to validate relevant - headers, but MUST NOT assume that missing headers or values are forbidden - from use. While schema authors MAY set "additionalProperties" to - false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents - from supplying additional headers when requests are made. - - - The exact mapping of the JSON data model into the headers is - protocol-dependent. However, in most cases this schema SHOULD - specify a type of "object", and the property names SHOULD be - lower-cased forms of the control data field names. - - - "headerSchema" is applicable to any request method or command that the - protocol supports. When generating a request, clients SHOULD ignore - schemas for headers that are not relevant to that request. - -
+
- Schemas SHOULD be written to describe JSON serializations that - follow guidelines established by the work in progress - "A JSON Encoding for HTTP Header Field Values" - Approaches shown in that document's examples SHOULD be applied to - other similarly structured headers wherever possible. + In JSON Hyper-Schema, "targetSchema" + supplies a non-authoritative description of the target resource's + representation. A client can use "targetSchema" to structure input for + replacing or modifying the representation, or as the base representation + for building a patch document based on a patch media type. - It is RECOMMENDED that schema authors describe the available usage of - the following types of HTTP headers whenever applicable: - - Content negotiation - Authentication and authorization - Range requests - The "Prefer" header - + Alternatively, if "targetSchema" is absent or if the client prefers to + only use authoritative information, it can interact with the target + resource to confirm or discover its representation structure. - Headers such as cache control and conditional request headers are generally - implemented by intermediaries rather than the resource, and are therefore - not generally useful to describe. While the resource must supply the - information needed to use conditional requests, the runtime handling of - such headers and related responses is not resource-specific. + "targetSchema" is not intended to describe link operation responses, + except when the response semantics indicate that it is a representation + of the target resource. In all cases, the schema indicated by the response + itself is authoritative. See + "JSON Hyper-Schema and HTTP" for detailed + examples. -
- - The "Prefer" header defined in RFC 7240 - is a good candidate for description in "headerSchema". It defines - several standard values and allows for extension values. - This schema indicates that the target understands the - "respond-async" preference, the "wait" preference which - takes a number of seconds to wait, as well as "minimal" and - "representation" for the "return" preference. - - - - - - Each name/value preference pair is a single value of the - header, so each object in the list can only have one such - pair. Simplifying the "response-async" value to a single string - is based on the "Accept-Encoding" example in - appendix A.4 of the JSON encoding draft. - -
+
+ +
- The Prefer header also stretches the limits of existing recommendations - for serializing HTTP headers in JSON. It is possible for both the - single string and name/value pair preferences to take additional - name/value parameters. While a single-string preference can accomodate - such parameters following the "Accept-Encoding" example, there is - no example to date of a name/value pair with parameters. - - We hope to get feedback from hyper-schema authors on what - practical concerns arise, and from there decide how best to - handle them. The specification for this keyword is expected to - become more well-defined in future drafts. - + The "submissionSchema" and + "submissionMediaType" keywords + describe the domain of the processing function implemented by the target + resource. Otherwise, as noted above, the submission schema and media type + are ignored for operations to which they are not relevant. + +
+ + If present, this property indicates the media type format the + client should use for the request payload described by + "submissionSchema". + + + Omitting this keyword has the same behavior as a value of + application/json. + + + Note that "submissionMediaType" and "submissionSchema" + are not restricted to HTTP URIs. + This statement might move to wherever the example ends up. + +
+ +
+ + This property contains a schema which defines the acceptable structure + of the document to be encoded according to the "submissionMediaType" + property and sent to the target resource for processing. This can be + viewed as describing the domain of the processing function implemented + by the target resource. + + + This is a separate concept from the + "targetSchema" property, which + describes the target information resource (including for replacing the + contents of the resource in a PUT request), unlike "submissionSchema" + which describes the user-submitted request data to be evaluated by the + resource. "submissionSchema" is intended for use with requests that + have payloads that are not necessarily defined in terms of the target + representation. + + + Omitting "submissionSchema" has the same behavior as a value of "true". + +
+
-
+
+ + At a high level, a conforming implementation will meet the following + requirements. Each of these requirements is covered in more detail in the + individual keyword sections and keyword group overviews. + + + Note that the requirements around how an implementation MUST recognize + "self", "collection", and "item" links are thoroughly covered in the + link relation type section and are not + repeated here. + + + While it is not a mandatory format for implementations, the output format used + in the test suite summarizes what needs to be computed for each link before + it can be used: + + + The fully resolved URI (with scheme) of the context resource. If + the context is not the entire resource and there is a usable fragment + identifier syntax, then the URI includes a fragment. Note that there + is no such syntax for application/json. + + + The JSON Pointer for the location within the instance of the context + resource. If the instance media type supports JSON Pointers as fragment + identifiers, this pointer will be the same as the one encoded in the + fragment of the "contextUri" field. + + + The link relation type, as it appears in the LDO. + + + The fully resolved URI (with a scheme) of the target resource. If the + link accepts input, this can only be produced once the input has been + supplied. + + + The list of partially resolved URI references for a link that accepts + input. The first entry in the list is the partially resolved "href". + The additional entries, if any, are the partially resolved "base" values + ordered from the most immediate out to the root of the schema. + Template variables that are pre-populated in the input are not resolved + at this stage, as the pre-populated value can be overridden. + + + The data set that the user agent should use to prepopulate any + input mechanism before accepting client input. If input is to be + accepted but no fields are to be pre-populated, then this will be + an empty object. + + + The JSON Pointer for the location within the instance to which the + link is attached. By default, "contextUri" and "attachementUri" are + the same, but "contextUri" can be changed by LDO keywords, while + "attachmentUri" cannot. + + + Other LDO keywords that are not involved in producing the above information + are included exactly as they appear when producing output for the test suite. + Those fields will not be further discussed here unless specifically relevant. + + +
- If present, this property indicates the media type format the - client should use for the request payload described by - "submissionSchema". + Before links can be used, they must be discovered by applying the hyper-schema + to the instance and finding all applicable and valid links. Note that in + addition to collecting valid links, any "base" + values necessary to resolve each LDO's URI Templates must also be located + and associated with the LDO through whatever mechanism is most useful for + the implementation's URI Template resolution process. - Omitting this keyword has the same behavior as a value of application/json. + And implementation MUST support looking up links by either their + attachment pointer or context pointer, either by performing the look-up + or by providing the set of all links with both pointers determined + so that user agents can implement the look-up themselves. - Note that "submissionMediaType" and "submissionSchema" - are not restricted to HTTP URIs. - -
- - For example, this link indicates that if you want to - send an email to the author of the context resource, - your client needs to ask for both a plain text - and an HTML representation. - - - - -
+ When performing look-ups by context pointer, links that are attached to + elements of the same array MUST be returned in the same order as the + array elements to which they are attached.
-
+
- This property contains a schema which defines the acceptable structure - of the document to be encoded according to the "submissionMediaType" property - and sent to the target resource for processing. This can be viewed as - describing the domain of the processing function implemented by the - target resource. + Three hyper-schema keywords are URI Templates: + "base", "anchor", and "href". Each are resolved separately to URI-references, + and then the anchor or href URI-reference is resolved against the base (which + is itself resolved against earlier bases as needed, each of which was first + resolved from a URI Template to a URI-reference). - - This is a separate concept from the - "targetSchema" property, which is describing - the target information resource (including for replacing the contents of the - resource in a PUT request), unlike "submissionSchema" which describes the - user-submitted request data to be evaluated by the resource. "submissionSchema" - is intended for use with requests that have payloads that are not defined in - terms of the target representation. + All three keywords share the same algorithm for resolving variables from + instance data, which makes use of the "templatePointers" and "templateRequired" + keywords. When resolving "href", both it and any "base" templates + needed for resolution to an absolute URI, the algorithm is modified to + optionally accept user input based on the "hrefSchema" keyword. - Omitting "submissionSchema" or setting the entire schema to "false" prevents - any user agent data from being accepted. + For each URI Template (T), the following pseudocode describes an algorithm for + resolving T into a URI-reference (R). For the purpose of this algorithm: + + + "ldo.templatePointers" is an empty object if the keyword was not + present and "ldo.templateRequired" is likewise an empty array. + + + "attachmentPointer" is the absolute JSON Pointer for the attachment + location of the LDO. + + + "getApplicableSchemas()" returns an iterable set of all (sub)schemas + that apply to the attachment point in the instance. + + -
-
-
- - Three hyper-schema keywords are URI Templates: - "base", "anchor", and "href". Each are resolved separately to URI-references, - and then the anchor or href URI-reference is resolved against the base (which - is itself resolved against earlier bases as needed, each of which was first - resolved from a URI Template to a URI-reference). - - - All three keywords share the same algorithm for resolving variables from - instance data, which makes use of the "templatePointers" and "templateRequired" - keywords. When resolving "href", both it and any "base" templates - needed for resolution to an absolute URI, the algorithm is modified to - optionally accept user input based on the "hrefSchema" keyword. - - - For each URI Template (T), the following pseudocode describes an algorithm for - resolving T into a URI-reference (R). For the purpose of this algorithm: - - - "ldo.templatePointers" is an empty object if the keyword was not - present and "ldo.templateRequired" is likewise an empty array. - - - "attachmentPointer" is the absolute JSON Pointer for the attachment - location of the LDO. - - - "getApplicableSchemas()" returns an iterable set of all (sub)schemas - that apply to the attachment point in the instance. - - - - - This algorithm should be applied first to either "href" or "anchor", - and then as needed to each successive "base". The order is important, - as it is not always possible to tell whether a template will resolve - to a full URI or a URI-reference. - - - In English, the high-level algorithm is: - - Populate template variable data from the instance - If input is desired, accept input - Check that all required variables have a value - Encode values into strings and fill out the template - - -
- - This is the high-level algorithm as pseudocode. "T" comes from either - "href" or "anchor" within the LDO, or from "base" in a containing schema. - Pseudocode for each step follows. "initialTemplateKeyword" indicates - which of the two started the process (since "base" is always resolved - in order to finish resolving one or the other of those keywords). - - + + This algorithm should be applied first to either "href" or "anchor", + and then as needed to each successive "base". The order is important, + as it is not always possible to tell whether a template will resolve + to a full URI or a URI-reference. + + + In English, the high-level algorithm is: + + Populate template variable data from the instance + If input is desired, accept input + Check that all required variables have a value + Encode values into strings and fill out the template + + +
+ + This is the high-level algorithm as pseudocode. "T" comes from either + "href" or "anchor" within the LDO, or from "base" in a containing schema. + Pseudocode for each step follows. "initialTemplateKeyword" indicates + which of the two started the process (since "base" is always resolved + in order to finish resolving one or the other of those keywords). + + - -
+ +
-
- - This step looks at various locations in the instance for variable values. - For each variable: - - - Use "templatePointers" to find a value if the variable - appears in that keyword's value - - - Otherwise, look for a property name matching the variable in - the instance location to which the link is attached - - - In either case, if there is a value at the location, put it in - the template resolution data set - - - -
- +
+ + This step looks at various locations in the instance for variable values. + For each variable: + + + Use "templatePointers" to find a value if the variable + appears in that keyword's value + + + Otherwise, look for a property name matching the variable in + the instance location to which the link is attached + + + In either case, if there is a value at the location, put it in + the template resolution data set + + + +
+ - -
-
+ +
+
-
- - This step is relatively complex, as there are several cases to support. - Some variables will forbid input and some will allow it. Some will - have initial values that need to be presented in the input interface, - and some will not. - - - - Figure out which variables can accept input - - Pre-populate the input data set if the template resolution data - set has a value - - Accept input (present a web form, make a callback, etc.) - Validate the input data set, (not the template resolution data set) - - Put the input in the template resolution data set, overriding - any existing values - - - -
- - "InputForm" represents whatevers sort of input mechanism is appropriate. - This may be a literal web form, or may be a more programmatic construct - such as a callback function accepting specific fields and data types, - with the given initial values, if any. - - +
+ + This step is relatively complex, as there are several cases to support. + Some variables will forbid input and some will allow it. Some will + have initial values that need to be presented in the input interface, + and some will not. + + + + + Deterimine which variables can accept input + + + Pre-populate the input data set if the template resolution data + set has a value + + + Accept input (present a web form, make a callback, etc.) + + + Validate the input data set, (not the template resolution data set) + + + Put the input in the template resolution data set, overriding + any existing values + + + +
+ + "InputForm" represents whatever sort of input mechanism is appropriate. + This may be a literal web form, or may be a more programmatic construct + such as a callback function accepting specific fields and data types, + with the given initial values, if any. + + - -
-
+ +
+
-
- - This section is straightforward, converting literals to their names - as strings, and converting numbers to strings in the most obvious manner, - and percent-encoding as needed for use in the URI. - -
- +
+ + This section is straightforward, converting literals to their names + as strings, and converting numbers to strings in the most obvious manner, + and percent-encoding as needed for use in the URI. + +
+ - - - In some software environments the original JSON representation of a - number will not be available (there is no way to tell the difference - between 1.0 and 1), so any reasonable representation should be used. - Schema and API authors should bear this in mind, and use other types - (such as string or boolean) if the exact representation is - important. If the number was provide as input in the form of a - string, the string used as input SHOULD be used. - -
+ + + In some software environments the original JSON representation of a + number will not be available (there is no way to tell the difference + between 1.0 and 1), so any reasonable representation should be used. + Schema and API authors should bear this in mind, and use other types + (such as string or boolean) if the exact representation is + important. If the number was provide as input in the form of a + string, the string used as input SHOULD be used. + +
+
+
+ +
+ + For a given link, an implementation MUST make the values of all + target attribute keywords directly available to the user agent. + Implementations MAY provide additional interfaces for using this + information, as discussed in each keyword's section. + + + For a given link, an implementation MUST make the value of each + input schema keyword directly available to the user agent. + + + To encourage encapsulation of the URI Template resolution process, + implementations MAY omit the LDO keywords that are used only to + construct URIs. However, implementations MUST provide access to + the link relation type. + + + Unrecognized keywords SHOULD be made available to the user agent, + and MUST otherwise be ignored. + +
+ +
+ + Implementations MAY provide additional functionality coordinating the use of + JSON Hyper-Schema with other specifications, including but not limited to + JSON Schema validation, serializing payloads based on media types, and + communicating with resources via protocols as indicated by URI schemes. + + This is vague. I'm trying to convey that most uses of Hyper-Schema + would benefit from including integration with the media types, URI schemes, + and protocols, such as automatically validating submission data against + "submissionSchema", encoding it according to "submissionMediaType", + examining the URI for the "http" or "https" scheme, validating JSON + representations of headers against "headerSchema", serializing them + into HTTP header format, and constructing the appropriate POST request. + While many of those activities are technically outside of the scope of + Hyper-Schema, coordinating all of them is specific to Hyper-Schema and + beneficial to automate. + + +
+ +
+ + The requirements around discovering links based on their context, or + using the context of links to identify collections, present unique + challenges when used with streaming parsers. It is not possible to + authoritatively fulfill these requirements without processing the entire + schema and instance documents. + + + Such implementations MAY choose to return non-authoritative answers + based on data processed to date. When offering this approach, + implementations MUST be clear on the nature of the response, and MUST + offer an option to block and wait until all data is processed and + an authoritative answer can be returned. + +
+
+ +
+ + While JSON Hyper-Schema is a hypermedia format and therefore protocol-independent, + it is expected that its most common use will be in HTTP systems, or systems + using protocols such as CoAP that are explicitly analogous to HTTP. + + + This section provides guidance on how to define links for use with each + common HTTP method, and how collection resources impose additional constraints + on the use of HTTP POST. Additionally, guidance is provided on hinting at + HTTP response header values and describing possible HTTP request headers + that are relevant to the given resource. + +
+ + Link Description Objects do not directly indicate what operations, such + as HTTP methods, are supported by the target resource. Instead, operations + should be inferred primarily from link relation types + and URI schemes. + + + This means that for each target resource and link relation type pair, schema + authors SHOULD only define a single LDO. While it is possible to use + "allow" with "targetHints" to repeat a relation type and target pair with + different HTTP methods marked as allowed, this is NOT RECOMMENDED and may + not be well-supported by conforming implementations. + + + All information necessary to use each HTTP method can be conveyed in a + single LDO as explained in this section. The "allow" field in "targetHints" + is intended simply to hint at which operations are supported, not to + separately define each operation. + + + Note, however, that a resource may always decline an operation at runtime, + for instance due to authorization failure, or due to other application state + that controls the operation's availability. + +
+
+ + The relationship between a resource's representation and HTTP requests and + responses is determined by RFC 7231, section 4.3.1 - + "GET", section 4.3.4 "PUT", and section 3.1.4.2, "Content-Location". + In particular, "targetSchema" suggests what a client can expect for the + response to an HTTP GET or any response for which the "Content-Location" + header is equal to the request URI, and what a client should send if it + replaces the resource in an HTTP PUT request. + + + The media type of the representation is given by the "targetMediaType" + field. Alternatively, possible available media types MAY be advertised + for HTTP-accessible resources using the "accept" field in "headerSchema", + corresponding to the HTTP "Accept" header. + + + Per RFC 5789, the request structure for an HTTP + PATCH is determined by the combination of "targetSchema" and the request + media type, which is conveyed by the "Accept-Patch" header. Media types + that are suitable for PATCH-ing define a syntax for expressing changes + to a document, which can be applied to the representation described by + "targetSchema" to determine the set of syntactically valid request payloads. + + + HTTP POST request payloads are described by the "submissionSchema" and + "submissionMediaType" fields. Additionally, the "Accept-Post" header + can be used to specify the necessary media type, and MAY be + advertised via the "targetHints" field. + + What happens if both are used? Also, "submissionSchema" is a MUST + to support, while "targetHints" are at most a SHOULD. But forbidding + the use of "Accept-Post" in "targetHints" seems incorrect. + + +
+
+ + It would be good to also include a section with CoAP examples. + + + JSON serializations of HTTP response header information SHOULD follow the + guidelines established by the work in progress + "A JSON Encoding for HTTP Header Field Values". + Approaches shown in that document's examples SHOULD be applied to other + similarly structured headers wherever possible. + + + No distinction is made between headers that may appear in responses to + different methods, such as HEAD vs OPTIONS. + + + It is RECOMMENDED that schema authors provide hints for the values of + the following types of HTTP headers whenever applicable: + + Method allowance + Method-specific request media types + Authentication challenges + + + + In general, headers that are likely to have different values at different + times SHOULD NOT be included in "targetHints". + +
+
+ + Schemas SHOULD be written to describe JSON serializations that + follow guidelines established by the work in progress + "A JSON Encoding for HTTP Header Field Values" + Approaches shown in that document's examples SHOULD be applied to + other similarly structured headers wherever possible. + + + It is RECOMMENDED that schema authors describe the available usage of + the following types of HTTP headers whenever applicable: + + Content negotiation + Authentication and authorization + Range requests + The "Prefer" header + + + + Headers such as cache control and conditional request headers are generally + implemented by intermediaries rather than the resource, and are therefore + not generally useful to describe. While the resource must supply the + information needed to use conditional requests, the runtime handling of + such headers and related responses is not resource-specific. + +
+
+ + When using HTTP, or a protocol such as CoAP that is explicitly analogous + to HTTP, this is done by POST-ing a representation of the individual + resource to be created to the collection resource. The process for + recognizing collection and item resources is described in + . +
+
+ Examples are being added in a subsequent PR. +
+ +
+ Need to reference the core and validation security considerations. +
+ + When link relation of "self" is used to denote a full representation of an + object, the user agent SHOULD NOT consider the representation to be the + authoritative representation of the resource denoted by the target URI if + the target URI is not equivalent to or a sub-path of the URI used to request + the resource representation which contains the target URI with the "self" + link. + +
+
+ + + This whole section needs more work, but I do like having security + concerns around target interactions consolidated and addressed as a whole. + + + + The "targetMediaType" property in link definitions defines the expected + format of the link's target. + However, this is advisory only, and MUST NOT be considered authoritative. + + + When choosing how to interpret data, the type information provided by the + server (or inferred from the filename, or any other usual method) MUST be + the only consideration, and the "targetMediaType" property of the link + MUST NOT be used. + User agents MAY use this information to determine how they represent the + link or where to display it (for example hover-text, opening in a new tab). + If user agents decide to pass the link to an external program, they SHOULD + first verify that the data is of a type that would normally be passed to + that external program. + + + This is to guard against re-interpretation of "safe" data, similar to the + precautions for "targetSchema". + + + The "targetSchema" keyword has similar security concerns to that of + "targetMediaType". + Clients MUST NOT use the value of this property to aid in the interpretation + of the data received in response to following the link, as this leaves + "safe" data open to re-interpretation. + +
+
+
+ + Thanks to + Gary Court, + Francis Galiegue, + Kris Zyp, + and Geraint Luff + for their work on the initial drafts of JSON Schema. + + + Thanks to + Jason Desrosiers, + Daniel Perrett, + Erik Wilde, + Ben Hutton, + Evgeny Poberezkin, + Brad Bowman, + Gowry Sankar, + Donald Pipowitch, + Dave Finlay, + and Denis Laxalde + for their submissions and patches to the document. + +
@@ -1760,33 +1486,85 @@ for varname in templateData: &rfc5789; &rfc5988; &rfc6573; + &rfc7230; &rfc7231; - &rfc7240; + &rfc7807; + &I-D.nottingham-rfc5988bis; - -
+
- Thanks to - Gary Court, - Francis Galiegue, - Kris Zyp, - and Geraint Luff - for their work on the initial drafts of JSON Schema. + Hypermedia APIs, which follow the constraints of the REST architectural + style, enable the creation of generic user agents. Such a user agent + has no application-specific knowledge. Rather, it understands pre-defined + media types, URI schemes, protocols, and link relations, often by recognizing + these and coordinating the use of existing software that implements support + for them. Client applications can then be built on top of such a user agent, + focusing on their own semantics and logic rather than the mechanics of the + interactions. - Thanks to - Jason Desrosiers, - Daniel Perrett, - Erik Wilde, - Ben Hutton, - Evgeny Poberezkin, - Brad Bowman, - Gowry Sankar, - Donald Pipowitch, - Dave Finlay, - and Denis Laxalde - for their submissions and patches to the document. + Hyper-schema is only concerned with one resource and set of associated links + at a time. Just as a web browser works with only one HTML page at a time, + with no concept of whether or how that page functions as part of a "site", + a hyper-schema-aware user agent works with one resource at a time, without + any concept of whether or how that resource fits into an API. + + + Therefore, hyper-schema is suitable for use within an API, but is not suitable + for the description of APIs as complete entities in their own right. There is + no way to describe concepts at the API scope, rather than the resource and + link scope, and such descriptions are outside of the boundaries + of JSON Hyper-Schema. +
+ + Since a given JSON Hyper-Schema is used with a single resource at a single + point in time, it has no inherent notion of versioning. However, a given + resource can change which schema or schemas it uses over time, and the + URIs of these schemas can be used to indicate versioning information. + When used with a media type that supports indicating a schema with a media + type parameter, these versioned schema URIs can be used in content negotiation. + + + A resource can indicate that it is an instance of multiple schemas, which allows + supporting multiple compatible versions simultaneously. A client application + can then make use of the hyper-schema that it recognizes, and ignore newer + or older versions. + +
+
+ + Because a hyper-schema represents a single resource at a time, it does not + provide for an enumeration of all possible responses to protocol operations + performed with links. Each response, including errors, is considered + its own (possibly anonymous) resource, and should identify its own + hyper-schema, and optionally use an appropriate media type such as + RFC 7807's "application/problem+json", + to allow the user agent or client application to interpret any + information that is provided beyond the protocol's own status reporting. + +
+
+ + It is possible to statically analyze a set of hyper-schemas without instance + data in order to generate output such as documentation or code. However, + the full feature set of both validation and hyper-schema cannot be accessed + without runtime instance data. + + + This is an intentional design choice to provide the maximum runtime + flexibility for hypermedia systems. JSON Schema as a media type allows for + establishing additional vocabularies for static analysis and content + generation, which are not addressed in this specification. Additionally, + individual systems may restrict their usage to subsets that can be + analyzed statically if full design-time description is a goal. + + Vocabularies for API documentation and other purposes have been + proposed, and contributions are welcome at + https://github.com/json-schema-org/json-schema-vocabularies + + +
@@ -1795,7 +1573,7 @@ for varname in templateData: - + diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index d96f2d10..dcd2d102 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -26,28 +26,28 @@ - + JSON Schema Validation: A Vocabulary for Structural Validation of JSON - + + Cloudflare, Inc.
- aaa@bzfx.net + henry@cloudflare.com
- +
- luffgd@gmail.com + aaa@bzfx.net
- - Cloudflare, Inc. +
- henry@cloudflare.com + luffgd@gmail.com
@@ -1433,7 +1433,7 @@ - + Added "if"/"then"/"else" Warn of possibly removing "dependencies" in the future diff --git a/links.json b/links.json index 131c2f7c..1712ef11 100644 --- a/links.json +++ b/links.json @@ -1,81 +1,85 @@ { - "$schema": "http://json-schema.org/draft-06/hyper-schema#", - "$id": "http://json-schema.org/draft-06/links#", + "$schema": "http://json-schema.org/draft-07-wip/hyper-schema#", + "$id": "http://json-schema.org/draft-07-wip/links#", "title": "Link Description Object", - "type": "object", - "required": [ "href" ], - "properties": { - "href": { - "type": "string", - "format": "uri-template" - }, - "templatePointers": { + "allOf": [ + { "required": [ "rel", "href" ] }, + { "$ref": "#/definitions/noRequiredFields" } + ], + "definitions": { + "noRequiredFields": { "type": "object", - "additionalProperties": { - "type": "string", - "anyOf": [ - { "format": "json-pointer" }, - { "format": "relative-json-pointer" } - ] + "properties": { + "anchor": { + "type": "string", + "format": "uri-template" + }, + "anchorPointer": { + "type": "string", + "anyOf": [ + { "format": "json-pointer" }, + { "format": "relative-json-pointer" } + ] + }, + "rel": { + "type": "string" + }, + "href": { + "type": "string", + "format": "uri-template" + }, + "hrefSchema": { + "allOf": [ + { "$ref": "http://json-schema.org/draft-07-wip/hyper-schema#" } + ] + }, + "templatePointers": { + "type": "object", + "additionalProperties": { + "type": "string", + "anyOf": [ + { "format": "json-pointer" }, + { "format": "relative-json-pointer" } + ] + } + }, + "templateRequired": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + "targetSchema": { + "$ref": "http://json-schema.org/draft-07-wip/hyper-schema#" + }, + "targetMediaType": { + "type": "string" + }, + "targetHints": { }, + "hrefSchema": { + "$ref": "http://json-schema.org/draft-07-wip/hyper-schema#" + }, + "headerSchema": { + "$ref": "http://json-schema.org/draft-07-wip/hyper-schema#" + }, + "submissionMediaType": { + "type": "string", + "default": "application/json" + }, + "submissionSchema": { + "$ref": "http://json-schema.org/draft-07-wip/hyper-schema#" + }, + "$comment": { + "type": "string" + } } - }, - "hrefSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "templateRequired": { - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - }, - "rel": { - "type": "string" - }, - "anchor": { - "type": "string", - "format": "uri-template" - }, - "anchorPointer": { - "type": "string", - "anyOf": [ - { "format": "json-pointer" }, - { "format": "relative-json-pointer" } - ] - }, - "title": { - "type": "string" - }, - "description": { - "type": "string" - }, - "targetSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "targetHints": { }, - "mediaType": { - "type": "string" - }, - "headerSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "submissionEncType": { - "type": "string", - "default": "application/json" - }, - "submissionSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "$comment": { - "type": "string" } } } diff --git a/schema.json b/schema.json index 72c32454..4d8330f4 100644 --- a/schema.json +++ b/schema.json @@ -1,6 +1,6 @@ { - "$schema": "http://json-schema.org/draft-06/schema#", - "$id": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07-wip/schema#", + "$id": "http://json-schema.org/draft-07-wip/schema#", "title": "Core schema meta-schema", "definitions": { "schemaArray": {