From 6f3d93bd9114793f3ae013ecd5d73c0d80867140 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 20 Oct 2017 10:52:53 -0700 Subject: [PATCH 01/23] "base" is a URI Template --- hyper-schema.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/hyper-schema.json b/hyper-schema.json index a342e497..84036996 100644 --- a/hyper-schema.json +++ b/hyper-schema.json @@ -50,7 +50,8 @@ "propertyNames": { "$ref": "#" }, "base": { - "type": "string" + "type": "string", + "format": "uri-template" }, "links": { "type": "array", From e24b38271ebbbe8403baec1318b896b318bb877e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 20 Oct 2017 11:12:24 -0700 Subject: [PATCH 02/23] Rewrite hyper-schema almost entirely Here are the main changes: * Set context in the overview and explain purpose. This should probably be trimmed back down some. * Start with a general, high-level definition of what it means to implement hyper-schema. This provides a framework for understanding the individual keywords. * Due to high-level requirements up front, and details of the whole URI Template resolution process, HTTP usage, security concerns, and API usage factored out to their own sections or appendices, the individual keyword sections focus on the key basic definitions * Schema keywords discussed in terms of applicability. Clarified requirements on how to handle "base". * LDO keywords restructured around the abstract link model * Context identification keywords first * Link relations next * Target identification rounds out the required concepts * Template process keywords, which apply to context and target * Target attributes (emphasize advisory nature in intro paragraph) * Input keywords, grouped by usage * links.json re-ordered to match * URI Template resolution process factored out to its own section, with pseudocode. Probably needs more explanatory text. * Security Considerations section instead of interrupting the flow of keywords as they are defined. * Consolidated HTTP usage notes into an appendix. This thoroughly covers how to use JSON Hyper-Schema with HTTP. * Added an appendix on how to use hyper-schema in APIs. This is probably the most likely to move out to the web site. I also was going to write more with analogies between API user agents and web browsers, but that got kind of bogged down so I stopped where it is now. * Added an appending on static analysis of hyper-schemas. This is where a lot of usage goes wrong in terms of expectations, so briefly addressing it in the spec seems wise. --- jsonschema-hyperschema.xml | 2370 ++++++++++++++++-------------------- links.json | 49 +- 2 files changed, 1060 insertions(+), 1359 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 7f368b56..9a271627 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -12,9 +12,11 @@ - + + + ]> @@ -66,10 +68,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,12 +93,14 @@
- 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. @@ -125,137 +129,235 @@
- 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. + + + 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 at runtime, such as HTTP Link headers or + JSON HAL. Because hyper-schema offers + a superset of the features of many other systems, using it on the server + can make it easier to support multiple representation media types and + linking mechanisms. It is even possible to support features such as JSON HAL's + embedded resources by automatically following links on the server and + inlining the results. -
- - 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. - -
The current URI for the JSON Hyper-Schema meta-schema is - <http://json-schema.org/draft-06/hyper-schema#>. + + http://json-schema.org/draft-06/hyper-schema# (draft-06 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. + A JSON Hyper-Schema implementation is able to take a hyper-schema, an + instance, and optionally an identification of a location within the instance + (such as a JSON Pointer or a URI fragment appropriate for the media type), + and produce information about any links that apply to that instance + or location. This information is returned in the form of URIs and/or JSON Pointers. + Additionally, some fields are intended for direct use by user agents and + client applications. - 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, - in resolution order, from the same schema and any parent schemas. + 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. -
+
- 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. + Before links can be used, they must be discovered. JSON Hyper-Schema provides + for two ways to discover links: based on the location in the instance to which + they are attached, and based on the link context. While the link context is + the traditional notion of the "source" end of the link, the attachment point + is often more useful with JSON instances, as it associates the link with + the JSON data to which it is most relevant. - The URI is computed from the provided URI template using the same process - described for the "href" property of a Link - Description Object. + In both approaches, the relevant "base" + values MUST be included as described in that keyword's section. -
- - 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: - - - - -
+
+ + An implementation MUST find and make the links in all applicable + (sub)schemas available to clients. Schema applicability is defined + in Section 10.1 of the JSON Schema + validation specification. Links that cannot fulfill + their "templateRequired" keyword based on the instance and/or potential + client input MUST be excluded. + + + These links MUST all be presented as a single set, regardless + of the number of subschemas involved. The order of links in the set + is not significant. + +
+
+ + Implementations MUST also make accessible the set of links for which + a given instance location is the link's context. All such links MUST + be in at least one set of links produced by examining schema applicability. + + + Link sets based on a context can include links attached to elements + of an ordered array. Implementations MUST preserve the order of + such links with respect to each other. Order is not otherwise significant. + +
+
+
+ + Once discovered, a link is generally selected based on its link relation + type, and used by communicating with the resource at the target URI. + This means that the target URI must be correctly computed based on the + instance data and optionally on input. The context URI must similarly + be calculated, although often only for use in context-based discovery + as described above. Finally, implementations need to recognize link + relation types that have well-known semantics within JSON Hyper-Schema. + +
+ + For a given link, an implementation MUST be able to identify the + link's context. The identifier MUST either be an IRI or URI + that fully identifies the context, or an IRI or URI together + with a JSON Pointer if the context is not an entire resource + and the representation's media type does not allow constructing an + appropriate fragment. + + + For a given link, an implementation MUST be able to construct the + target IRI or URI based on the instance and, if "hrefSchema" is present, + client input. When working with client input, the input data MUST be + pre-populated from the instance when a template variable matches instance + data and is present in "hrefSchema". + + + For both context and target URIs, this requirement includes + determining the correct base URI when the target is provided as + a relative reference. + + + In order to encourage treating context and target URIs as opaque + identifiers, implementations MAY opt to hide those fields that + are only used in URI construction ("href", "templatePointers", + "templateRequired", "anchor", and "anchorPointer") when making + the remainder of the LDO available to clients. Implementations + MAY offer a configuration option to enable or disable encapsulation. + +
+
+ + Implementations MUST recognize a link with a "self" relation typd as + describing the possible interactions with the resource represented by + the instance data. Collections MUST be recognized based on traversing + a "collection" link, or on discovering an "item" link which has the + instance or sub-instance as its context. + +
+
+ + For a given link, an implementation MUST make the values of all + target attribute keywords directly available to the client. + Implementations MAY provide additional interfaces for using this + information, which is 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 client. + +
+
+
- If the document URI is <http://example.com/?id=41>, then the new URI base - becomes <http://example.com/object/41> + 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. + +
+
- 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 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 requirments without processing the entire + schema and instance documents. + + + Such implementations MAY chooose 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. + +
+
+
+ + 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 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. + + + 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 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. + + + 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,1241 +367,567 @@ 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. + + + 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. - 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). + + http://json-schema.org/draft-06/links# (draft-06 version). -
+
- - 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). - + 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. - An operation is a specific use of a link described by an LDO, after any - template variables have been resolved. + 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. - 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. + 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 construcing a URI based on a URI template + is given in the URI Templating section. - - 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. - -
+
- 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. - - - This property is REQUIRED. - - -
- -
+
- 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. + The link's relation type identifies its semantics. It is the primary + means of conveying how an application can interact with a resource. - - 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 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. - - - 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. - - -
- -
- - 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. - -
- - 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. - - - - -
-
- -
- - 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. - - - - 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. - - - - 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. - - Relationship definitions are not normally media type dependent, and users are encouraged to utilize the most suitable existing accepted relation definitions. - - - 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". - -
- - - Note that these relationship values are case-insensitive, consistent with their - use in HTML and the HTTP Link header. - -
+
+ + 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 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. + the "item" and "collection" link relation types. JSON Hyper-Schema imposes + additional semantics on collection resources indicated by these types. - 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 "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 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". - -
+ 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. + + + 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 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): - - - - -
+
+ + 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.
- -
+
- 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. + 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 resolvling 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. + +
-
- - 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. + The keywords in this section are used when resolving all URI Tempaltes + involved in hyper-schema: "base", "anchor", and "href". See the + URI Templating section for the complete + template resolution algorithm. - 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. + 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" kewyord 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. + +
-
+
- This property defines a title for the link. - The value MUST be a string. + 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 +
+ + 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. - -
+ + 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. - +
+ + 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. - -
+ + 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. +
+ + 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".
-
- - 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. - - -
- - 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. - -
- - - 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). - -
+ +
+ + 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.
-
-
- - - 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. - - - 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. + + 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. + - 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. + 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. - 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 - + 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. + + + 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. - In general, headers that are likely to have different values at different - times SHOULD NOT be included in "targetHints". - - - No distinction is made between headers that may appear in responses to - different methods, such as HEAD vs OPTIONS. - -
- - This examples shows several hints that are useful for clients - when determining what requests to make and how to make them. - - - - -
+ See "JSON Hyper-Schema and HTTP" for + guidance on using this keyword with HTTP and analogous protocols. +
- -
- - 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. + 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. - -
+
+ + 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". + - 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. + Omitting "hrefSchema" or setting the entire schema to "false" prevents + any user agent data from being accepted. - - 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. + 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. - - This is to guard against re-interpretation of "safe" data, similar to the - precautions for "targetSchema". + 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. -
-
- -
- - - 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. + 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. - 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 - + 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. +
+ +
- 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. - -
- - 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. + 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. 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. +
-
-
- - 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. +
+ + 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. + + + 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. + + + "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. + +
-
- - 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. - - - - -
- -
+
+ + 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 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. - +
+ + 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 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. - - - Omitting "submissionSchema" or setting the entire schema to "false" prevents - any user agent data from being accepted. - +
+ + 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" or setting the entire schema to "false" + prevents any user agent data from being accepted. + + Is this correct? In draft-06 this was the only way to signal + support for data submission, but now we have "targetHints" for + that. It may make more sense for this to default to behaving + as if the schema is set to true. The original idea was that + both this keyword and "hrefSchema" indicated the presence + of optional functionality. This makes sense for "hrefSchema", + as it is used with "href" which is owned by the hyper-schema. + However, "submissionSchema" describes a message that is + supposedly accepted by the target resource. In general, we + choose defaults that avoid constraining target behavior. + + +
+
-
+ +
Three hyper-schema keywords are URI Templates: "base", "anchor", and "href". Each are resolved separately to URI-references, @@ -1511,7 +939,7 @@ GET /foo/ 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 + needed for resolution to an absolute URI, the algorithm is modfied to optionally accept user input based on the "hrefSchema" keyword. @@ -1538,28 +966,17 @@ GET /foo/ 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 is the high-level algorithm. "T" comes from either "href" + or "anchor" within the LDO, or from "base" in a containing schema. + Pseudocode for each step follows.
- - 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, + such as a callback funciton accepting specific fields and data types, with the given initial values, if any. @@ -1679,11 +1057,6 @@ return inputData:
- - 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. -
+
+ 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. + +
@@ -1761,31 +1206,282 @@ for varname in templateData: &rfc5988; &rfc6573; &rfc7231; - &rfc7240; + &I-D.nottingham-rfc5988bis; + &I-D.kelly-json-hal; + &ldp; - -
+
- Thanks to - Gary Court, - Francis Galiegue, - Kris Zyp, - and Geraint Luff - for their work on the initial drafts of JSON Schema. + 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. - 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. + This appendix provides guidance on how to define links for use with each + common HTTP method, and how collection resources impose additional constarints + on the use of HTTP POST. Additionaly, 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 appendix. + + + 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 + using an entry for the "Accept" request header field in "headerSchema". + + + 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. + + + HTTP POST requests are determined by the "submissionSchema" and + "submissionMediaType" fields. Alternatively, the "Accept-Post" header has + been defined and registered by the + Linked Data Platform, 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. + +
+
+
+ + 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 implement support + for them. 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. + + + JSON Hyper-Schema is ideal for representing individual resources in hypermedia + APIs. It offers comprehensive capabilities for describing how to use hyperlinks + to interact with the current resource (through "self" links), or related + resources. Using a hyper-schema-based API involves traversing links from + one resource to the next, interacting with resources through their + representations as described by the target keywords, or submitting data + to resources for processing using the submission keywords. + + + 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. + + + While aspects of cross-cutting API concerns such as authentication + and authorization may be described in hyper-schema, for instance in + the headerSchema of a link, defining an API-wide approach to any + cross-cutting concerns is beyond the scope of hyper-schema. + +
+ + Working with a JSON Hyper-Schema-based API will generally involve + three components: The hyper-schema implementation, a generic user agent, + and a client application. The hyper-schema implementation's requirements + are given in this specification. The generic user agent handles standardized + URI schemes, protocols, and media types. User agents that handle HTTP, + HTTPS, and JSON, for instance, are available as libraries in many programming + languages. + + + The client application has the domain-specific knowledge of link relation + types and data structure fields needed to make use of the specific API. + A client application can use an available user agent library and a hyper-schema + implementation separately. Alternatively, extensible user agents can allow + adding hyper-schema support as a plug-in alongside support for plain JSON, XML, + or other media types. + + + + Add something about generic user agents not being magic, HATEOAS, etc. + + +
+
+ + 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. + + + Note that this notion of changing the representaiton version using + successive hyper-schemas is separate from deprecating an entire resource + and either removing it or replacing it with a new resource at a new URI. + The "targetHints" keyword can be used to convey deprecation information. + + + + This section is something of a placeholder, with the goal being to + get readers to understand that while hyper-schema helps with versioning, + it does not and will not have explicit features to support it. + + +
+
+ + To create an entry point for an API, it is RECOMMENDED to provide + a resource at a documented entry point URI with the minimal amount of data + necessary to begin interacting with API resources. + The hyper-schema for this resource SHOULD contain links to all + API resources that can be accessed with only user input and/or + data contained in the entry point resource's representation. + +
+
+ + 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 to allow the user agent or client application to interpret any + information that is provided beyond the protocol's own status reporting. + + + Protocol and media type specifications provide the necessary information to + deal with different responses at runtime, while documenting all responses + is a concern static analysis across all hyper-schemas making up an API. + +
+
+
+ + 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 +
diff --git a/links.json b/links.json index 131c2f7c..80f96d2d 100644 --- a/links.json +++ b/links.json @@ -5,10 +5,29 @@ "type": "object", "required": [ "href" ], "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-06/hyper-schema#" } + ] + }, "templatePointers": { "type": "object", "additionalProperties": { @@ -19,11 +38,6 @@ ] } }, - "hrefSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, "templateRequired": { "type": "array", "items": { @@ -31,20 +45,6 @@ }, "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" }, @@ -56,16 +56,21 @@ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } ] }, - "targetHints": { }, - "mediaType": { + "targetMediaType": { "type": "string" }, + "targetHints": { }, + "hrefSchema": { + "allOf": [ + { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } + ] + }, "headerSchema": { "allOf": [ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } ] }, - "submissionEncType": { + "submissionMediaType": { "type": "string", "default": "application/json" }, From 04715a1e09d3731b7ec632acc5fd42fb0e9eb3e5 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 28 Sep 2017 15:22:07 -0700 Subject: [PATCH 03/23] Add more English descriptions --- jsonschema-hyperschema.xml | 50 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 9a271627..b50b42e5 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -966,10 +966,19 @@ 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. "T" comes from either "href" - or "anchor" within the LDO, or from "base" in a containing schema. + 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. @@ -992,6 +1001,17 @@ R = rfc6570ResolutionAlgorithm(T, templateData)
+ + This step looks at various data sources in the instance: + + Use "templatePointers" to find values where appropriate + Look in the immediate instance for remaining values + + Either way, if there is a value there, 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. @@ -1057,6 +1098,11 @@ return inputData:
+ + 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. +
Date: Thu, 28 Sep 2017 16:18:53 -0700 Subject: [PATCH 04/23] Use numbered lists for steps --- jsonschema-hyperschema.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index b50b42e5..2a2491b8 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -968,7 +968,7 @@ 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 @@ -1003,7 +1003,7 @@ R = rfc6570ResolutionAlgorithm(T, templateData)
This step looks at various data sources in the instance: - + Use "templatePointers" to find values where appropriate Look in the immediate instance for remaining values @@ -1041,7 +1041,7 @@ for varname in T: and some will not. - + Figure out which variables can accept input Pre-populate the input data set if the template resolution data From 1f7fd393679898df9f060b926fcb1e9ec9395ed1 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 14:35:16 -0700 Subject: [PATCH 05/23] Default "submissionSchema" to true Now that we have "targetHints" which, among other things, can provide information about which HTTP methods are supported, there is no longer a clear need to prevent submission by default. It is more in line with the rest of JSON Schema's philosophy to allow unconstrained input by default. Note that "hrefSchema" remains false by default due to its interaction with resolving URI Templates from instance data. --- jsonschema-hyperschema.xml | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 2a2491b8..fae72ad9 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -907,20 +907,7 @@ representation. - Omitting "submissionSchema" or setting the entire schema to "false" - prevents any user agent data from being accepted. - - Is this correct? In draft-06 this was the only way to signal - support for data submission, but now we have "targetHints" for - that. It may make more sense for this to default to behaving - as if the schema is set to true. The original idea was that - both this keyword and "hrefSchema" indicated the presence - of optional functionality. This makes sense for "hrefSchema", - as it is used with "href" which is owned by the hyper-schema. - However, "submissionSchema" describes a message that is - supposedly accepted by the target resource. In general, we - choose defaults that avoid constraining target behavior. - + Omitting "submissionSchema" has the same behavior as a value of "true".
From db7fe7c34cc6fb82557fd39530feadfcb2d02924 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 14:44:08 -0700 Subject: [PATCH 06/23] Introduce the LDO in the introduction and note that it is a serialization of the abstract link model from RFC 5988bis --- jsonschema-hyperschema.xml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index fae72ad9..0c7dc48a 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -102,7 +102,15 @@ 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 From 8e7b8da0b17a301a5990e8a94d28a86b87e6e206 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 15:06:13 -0700 Subject: [PATCH 07/23] Condense server-side usage overview It does not need as much detail, and I had left out the important application towards server push. --- jsonschema-hyperschema.xml | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 0c7dc48a..ce7425c2 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -14,7 +14,6 @@ - ]> @@ -160,17 +159,9 @@ 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 at runtime, such as HTTP Link headers or - JSON HAL. Because hyper-schema offers - a superset of the features of many other systems, using it on the server - can make it easier to support multiple representation media types and - linking mechanisms. It is even possible to support features such as JSON HAL's - embedded resources by automatically following links on the server and - inlining the results. + 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 faciliate server push usage.
@@ -1248,7 +1239,6 @@ for varname in templateData: &rfc6573; &rfc7231; &I-D.nottingham-rfc5988bis; - &I-D.kelly-json-hal; &ldp;
From 69f3e3bf08a0770b4f4814e7b4336182f90070e5 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 15:14:26 -0700 Subject: [PATCH 08/23] Keep specific keywords out of general concerns --- jsonschema-hyperschema.xml | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index ce7425c2..70b9867a 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -188,7 +188,7 @@ Each of these requirements is covered in more detail in the individual keyword sections and keyword group overviews. -
+
Before links can be used, they must be discovered. JSON Hyper-Schema provides for two ways to discover links: based on the location in the instance to which @@ -201,14 +201,19 @@ In both approaches, the relevant "base" values MUST be included as described in that keyword's section. + + Note that not all discovered links will necessarily be valid for use with + the specific instance at hand. Links may be unusable due to the contents + of the instance or input, as described in the keywords controlling the + link construction process. +
An implementation MUST find and make the links in all applicable (sub)schemas available to clients. Schema applicability is defined in Section 10.1 of the JSON Schema - validation specification. Links that cannot fulfill - their "templateRequired" keyword based on the instance and/or potential - client input MUST be excluded. + validation specification. Links that are not valid with the + current instance and/or client input MUST be excluded. These links MUST all be presented as a single set, regardless @@ -250,10 +255,9 @@ For a given link, an implementation MUST be able to construct the - target IRI or URI based on the instance and, if "hrefSchema" is present, - client input. When working with client input, the input data MUST be - pre-populated from the instance when a template variable matches instance - data and is present in "hrefSchema". + target IRI or URI based on the instance and/or client input. + When working with client input, the input data MUST be pre-populated + from the instance as controlled by the link construction keywords. For both context and target URIs, this requirement includes @@ -262,10 +266,9 @@ In order to encourage treating context and target URIs as opaque - identifiers, implementations MAY opt to hide those fields that - are only used in URI construction ("href", "templatePointers", - "templateRequired", "anchor", and "anchorPointer") when making - the remainder of the LDO available to clients. Implementations + identifiers, implementations MAY opt to hide those keywords that + are only used in URI construction when making the remainder of the + Link Description Object available to clients. Implementations MAY offer a configuration option to enable or disable encapsulation.
From e92b41719264aae8c18affc5f239836b9f47d073 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 16:40:02 -0700 Subject: [PATCH 09/23] Exclude LDO schema keywords from applicability When discovering links for a hyper-schema, it does not make sense to examine the schema keywords within the discovered links. While this was already the case as there are no rules for determining the applicability of those keywords to an instance, that is not obvious so make it explicit. --- jsonschema-hyperschema.xml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 70b9867a..37e7e496 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -215,6 +215,12 @@ validation specification. Links that are not valid with the current instance and/or client input MUST be excluded. + + Schemas that are found as values within Link Description Objects + are not considered to be applicable to the instance, even when the + link is applicable and valid. They are only applied to various kinds + of input or message payloads as described for each keyword. + These links MUST all be presented as a single set, regardless of the number of subschemas involved. The order of links in the set From 7d64e918caae1d3ac6cc4dc037360b411558391d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 19:53:28 -0700 Subject: [PATCH 10/23] Wording improvements from PR review Define the condition for using hrefSchema more clearly (I hope). Use consistent language around "locations" in a schema rather than introduce a new term "data sources" which is not defined. Attempt a better explanation of how to find values in the instance. I'm not entirely sure it's successful but at least it's different. --- jsonschema-hyperschema.xml | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 37e7e496..29c84df1 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -974,13 +974,15 @@ 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. + Pseudocode for each step follows. "anchorOrHref" 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 data sources in the instance: + This step looks at various locations in the instance for variable values. + For each variable: - Use "templatePointers" to find values where appropriate - Look in the immediate instance for remaining values - Either way, if there is a value there, put it in the - template resolution data set + Use "templatePointers" to find a value if the variable + appears in that keyword's value + + + Otherwise, look for a property names 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 From c5cc781cda4e4a8c6514b8f332e0837c0f00530f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 8 Oct 2017 23:49:16 -0700 Subject: [PATCH 11/23] Remove commented text, simplify Accept-Post Minor tidying and removal of an unnecessary reference. --- jsonschema-hyperschema.xml | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 29c84df1..798cd512 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -15,7 +15,6 @@ - ]> @@ -1257,7 +1256,6 @@ for varname in templateData: &rfc6573; &rfc7231; &I-D.nottingham-rfc5988bis; - &ldp;
@@ -1300,8 +1298,8 @@ for varname in templateData: 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 + "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. @@ -1318,9 +1316,8 @@ for varname in templateData: HTTP POST requests are determined by the "submissionSchema" and - "submissionMediaType" fields. Alternatively, the "Accept-Post" header has - been defined and registered by the - Linked Data Platform, and MAY be + "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 @@ -1328,15 +1325,6 @@ for varname in templateData: the use of "Accept-Post" in "targetHints" seems incorrect. -
From 0dbd8a8adc4be9274ad0d4800685436a468e20b8 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 9 Oct 2017 11:57:36 -0700 Subject: [PATCH 12/23] Fix more typos, better variable name. --- jsonschema-hyperschema.xml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 798cd512..7060a702 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -933,7 +933,7 @@ 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 modfied to + needed for resolution to an absolute URI, the algorithm is modified to optionally accept user input based on the "hrefSchema" keyword. @@ -973,15 +973,15 @@ 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. "anchorOrHref" 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). + 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). - Otherwise, look for a property names matching the variable in + Otherwise, look for a property name matching the variable in the instance location to which the link is attached @@ -1062,7 +1062,7 @@ for varname in T: "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 funciton accepting specific fields and data types, + such as a callback function accepting specific fields and data types, with the given initial values, if any. From 175852e7873a4555ac9142fcb5a4edc0ca745335 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 12 Oct 2017 17:37:42 -0700 Subject: [PATCH 13/23] Keep initial functionality description high-level Re-organize the first few sections a bit (based on looking at how several other relatively recent RFCs organize things). Have an explicit list of referenced and defined terms (at least one OAuth 2.0 RFC does this and it seems useful). With the terms defined, cover the most important implementation requirements at a *very* high level, without getting into more confusing cases such as how to handle streaming data. Move the old section down after the LDO section and before URI Templating. The contents have not been changed aside from chopping off the introduction which was used as the starting point for the remaining early section. URI Templating will need to move into the implementation section, which will need substantial reworking to accomodate that and its new position in the flow of the schema. This will be done in subsequent commits. --- jsonschema-hyperschema.xml | 437 ++++++++++++++++++++++--------------- 1 file changed, 266 insertions(+), 171 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 7060a702..965ffb78 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -11,6 +11,7 @@ + @@ -117,7 +118,7 @@
-
+
@@ -126,11 +127,6 @@ "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. -
@@ -162,180 +158,129 @@ other link serializations or representation formats at runtime, or pre-emptively follow links to faciliate server push usage. -
-
- - The current URI for the JSON Hyper-Schema meta-schema is - - http://json-schema.org/draft-06/hyper-schema# (draft-06 version). - -
- -
- - A JSON Hyper-Schema implementation is able to take a hyper-schema, an - instance, and optionally an identification of a location within the instance - (such as a JSON Pointer or a URI fragment appropriate for the media type), - and produce information about any links that apply to that instance - or location. This information is returned in the form of URIs and/or JSON Pointers. - Additionally, some fields are intended for direct use by user agents and - client applications. - - - 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. - -
+
- Before links can be used, they must be discovered. JSON Hyper-Schema provides - for two ways to discover links: based on the location in the instance to which - they are attached, and based on the link context. While the link context is - the traditional notion of the "source" end of the link, the attachment point - is often more useful with JSON instances, as it associates the link with - the JSON data to which it is most relevant. + The terms "schema", "instance", and "meta-schema" are to be interpreted as + defined in the JSON Schema core specification. - In both approaches, the relevant "base" - values MUST be included as described in that keyword's section. + The terms "applicable" and "attached" are to be interpreted as defined in + Section 10.1 of the + JSON Schema validation specification. - Note that not all discovered links will necessarily be valid for use with - the specific instance at hand. Links may be unusable due to the contents - of the instance or input, as described in the keywords controlling the - link construction process. + 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. -
- - An implementation MUST find and make the links in all applicable - (sub)schemas available to clients. Schema applicability is defined - in Section 10.1 of the JSON Schema - validation specification. Links that are not valid with the - current instance and/or client input MUST be excluded. - - - Schemas that are found as values within Link Description Objects - are not considered to be applicable to the instance, even when the - link is applicable and valid. They are only applied to various kinds - of input or message payloads as described for each keyword. - - - These links MUST all be presented as a single set, regardless - of the number of subschemas involved. The order of links in the set - is not significant. - -
-
- - Implementations MUST also make accessible the set of links for which - a given instance location is the link's context. All such links MUST - be in at least one set of links produced by examining schema applicability. - - - Link sets based on a context can include links attached to elements - of an ordered array. Implementations MUST preserve the order of - such links with respect to each other. Order is not otherwise significant. - -
-
-
- Once discovered, a link is generally selected based on its link relation - type, and used by communicating with the resource at the target URI. - This means that the target URI must be correctly computed based on the - instance data and optionally on input. The context URI must similarly - be calculated, although often only for use in context-based discovery - as described above. Finally, implementations need to recognize link - relation types that have well-known semantics within JSON Hyper-Schema. + 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. -
- - For a given link, an implementation MUST be able to identify the - link's context. The identifier MUST either be an IRI or URI - that fully identifies the context, or an IRI or URI together - with a JSON Pointer if the context is not an entire resource - and the representation's media type does not allow constructing an - appropriate fragment. - - - For a given link, an implementation MUST be able to construct the - target IRI or URI based on the instance and/or client input. - When working with client input, the input data MUST be pre-populated - from the instance as controlled by the link construction keywords. - - - For both context and target URIs, this requirement includes - determining the correct base URI when the target is provided as - a relative reference. - - - In order to encourage treating context and target URIs as opaque - identifiers, implementations MAY opt to hide those keywords that - are only used in URI construction when making the remainder of the - Link Description Object available to clients. Implementations - MAY offer a configuration option to enable or disable encapsulation. - -
-
- - Implementations MUST recognize a link with a "self" relation typd as - describing the possible interactions with the resource represented by - the instance data. Collections MUST be recognized based on traversing - a "collection" link, or on discovering an "item" link which has the - instance or sub-instance as its context. - -
-
- - For a given link, an implementation MUST make the values of all - target attribute keywords directly available to the client. - Implementations MAY provide additional interfaces for using this - information, which is 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 client. - -
-
-
- 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. - + 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. + +
-
+ +
- 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 requirments without processing the entire - schema and instance documents. + 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. - Such implementations MAY chooose 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. + 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-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). + + + While implementations are free to provide output in any format, the format + used for examples in this document is also used by the conformance test suite, + and is therefore a good default output format. The URI of the JSON Schema + describing that format is + + http://json-schema.org/draft-7-wip/hyper-schema-output# + (draft-07 work-in-progress version). + +
Hyper-schema keywords from all schemas that are applicable to a position @@ -377,7 +322,7 @@
-
+
This section references the work-in-progress RFC5988bis, with the expectation @@ -410,14 +355,6 @@ MUST be present. Each keyword is covered briefly in this section, with additional usage explanation and comprehensive examples given later in the document. - - 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). -
@@ -921,6 +858,163 @@
+
+ THIS SECTION HAS JUST BEEN MOVED! It will be reworked soon + + 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. + +
+ + Before links can be used, they must be discovered. JSON Hyper-Schema provides + for two ways to discover links: based on the location in the instance to which + they are attached, and based on the link context. While the link context is + the traditional notion of the "source" end of the link, the attachment point + is often more useful with JSON instances, as it associates the link with + the JSON data to which it is most relevant. + + + In both approaches, the relevant "base" + values MUST be included as described in that keyword's section. + + + Note that not all discovered links will necessarily be valid for use with + the specific instance at hand. Links may be unusable due to the contents + of the instance or input, as described in the keywords controlling the + link construction process. + +
+ + An implementation MUST find and make the links in all applicable + (sub)schemas available to clients. Schema applicability is defined + in Section 10.1 of the JSON Schema + validation specification. Links that are not valid with the + current instance and/or client input MUST be excluded. + + + Schemas that are found as values within Link Description Objects + are not considered to be applicable to the instance, even when the + link is applicable and valid. They are only applied to various kinds + of input or message payloads as described for each keyword. + + + These links MUST all be presented as a single set, regardless + of the number of subschemas involved. The order of links in the set + is not significant. + +
+
+ + Implementations MUST also make accessible the set of links for which + a given instance location is the link's context. All such links MUST + be in at least one set of links produced by examining schema applicability. + + + Link sets based on a context can include links attached to elements + of an ordered array. Implementations MUST preserve the order of + such links with respect to each other. Order is not otherwise significant. + +
+
+
+ + Once discovered, a link is generally selected based on its link relation + type, and used by communicating with the resource at the target URI. + This means that the target URI must be correctly computed based on the + instance data and optionally on input. The context URI must similarly + be calculated, although often only for use in context-based discovery + as described above. Finally, implementations need to recognize link + relation types that have well-known semantics within JSON Hyper-Schema. + +
+ + For a given link, an implementation MUST be able to identify the + link's context. The identifier MUST either be an IRI or URI + that fully identifies the context, or an IRI or URI together + with a JSON Pointer if the context is not an entire resource + and the representation's media type does not allow constructing an + appropriate fragment. + + + For a given link, an implementation MUST be able to construct the + target IRI or URI based on the instance and/or client input. + When working with client input, the input data MUST be pre-populated + from the instance as controlled by the link construction keywords. + + + For both context and target URIs, this requirement includes + determining the correct base URI when the target is provided as + a relative reference. + + + In order to encourage treating context and target URIs as opaque + identifiers, implementations MAY opt to hide those keywords that + are only used in URI construction when making the remainder of the + Link Description Object available to clients. Implementations + MAY offer a configuration option to enable or disable encapsulation. + +
+
+ + Implementations MUST recognize a link with a "self" relation typd as + describing the possible interactions with the resource represented by + the instance data. Collections MUST be recognized based on traversing + a "collection" link, or on discovering an "item" link which has the + instance or sub-instance as its context. + +
+
+ + For a given link, an implementation MUST make the values of all + target attribute keywords directly available to the client. + Implementations MAY provide additional interfaces for using this + information, which is 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 client. + +
+
+
+ + 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 requirments without processing the entire + schema and instance documents. + + + Such implementations MAY chooose 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. + +
+
+
Three hyper-schema keywords are URI Templates: @@ -1254,6 +1348,7 @@ for varname in templateData: &rfc5789; &rfc5988; &rfc6573; + &rfc7230; &rfc7231; &I-D.nottingham-rfc5988bis; From 95aed67e4427230da6f613484a11b10ec6621639 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 13 Oct 2017 12:43:33 -0700 Subject: [PATCH 14/23] Rework implementation requirements from move Now that the implementation requirements have been moved down below the keywords, they can be substantially trimmed down and the URI Templating section can be brought in with the other implementation requirements. --- jsonschema-hyperschema.xml | 541 ++++++++++++++++++------------------- 1 file changed, 269 insertions(+), 272 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 965ffb78..49cf245e 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -473,7 +473,8 @@ 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. + 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 @@ -859,219 +860,147 @@
- THIS SECTION HAS JUST BEEN MOVED! It will be reworked soon 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. + + +
- Before links can be used, they must be discovered. JSON Hyper-Schema provides - for two ways to discover links: based on the location in the instance to which - they are attached, and based on the link context. While the link context is - the traditional notion of the "source" end of the link, the attachment point - is often more useful with JSON instances, as it associates the link with - the JSON data to which it is most relevant. + 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. - In both approaches, the relevant "base" - values MUST be included as described in that keyword's section. + And implementation MUST support looking up links by either their + attachement 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 not all discovered links will necessarily be valid for use with - the specific instance at hand. Links may be unusable due to the contents - of the instance or input, as described in the keywords controlling the - link construction process. + 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. -
- - An implementation MUST find and make the links in all applicable - (sub)schemas available to clients. Schema applicability is defined - in Section 10.1 of the JSON Schema - validation specification. Links that are not valid with the - current instance and/or client input MUST be excluded. - - - Schemas that are found as values within Link Description Objects - are not considered to be applicable to the instance, even when the - link is applicable and valid. They are only applied to various kinds - of input or message payloads as described for each keyword. - - - These links MUST all be presented as a single set, regardless - of the number of subschemas involved. The order of links in the set - is not significant. - -
-
- - Implementations MUST also make accessible the set of links for which - a given instance location is the link's context. All such links MUST - be in at least one set of links produced by examining schema applicability. - - - Link sets based on a context can include links attached to elements - of an ordered array. Implementations MUST preserve the order of - such links with respect to each other. Order is not otherwise significant. - -
-
+ +
- Once discovered, a link is generally selected based on its link relation - type, and used by communicating with the resource at the target URI. - This means that the target URI must be correctly computed based on the - instance data and optionally on input. The context URI must similarly - be calculated, although often only for use in context-based discovery - as described above. Finally, implementations need to recognize link - relation types that have well-known semantics within JSON Hyper-Schema. + 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). -
- - For a given link, an implementation MUST be able to identify the - link's context. The identifier MUST either be an IRI or URI - that fully identifies the context, or an IRI or URI together - with a JSON Pointer if the context is not an entire resource - and the representation's media type does not allow constructing an - appropriate fragment. - - - For a given link, an implementation MUST be able to construct the - target IRI or URI based on the instance and/or client input. - When working with client input, the input data MUST be pre-populated - from the instance as controlled by the link construction keywords. - - - For both context and target URIs, this requirement includes - determining the correct base URI when the target is provided as - a relative reference. - - - In order to encourage treating context and target URIs as opaque - identifiers, implementations MAY opt to hide those keywords that - are only used in URI construction when making the remainder of the - Link Description Object available to clients. Implementations - MAY offer a configuration option to enable or disable encapsulation. - -
-
- - Implementations MUST recognize a link with a "self" relation typd as - describing the possible interactions with the resource represented by - the instance data. Collections MUST be recognized based on traversing - a "collection" link, or on discovering an "item" link which has the - instance or sub-instance as its context. - -
-
- - For a given link, an implementation MUST make the values of all - target attribute keywords directly available to the client. - Implementations MAY provide additional interfaces for using this - information, which is 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 client. - -
-
-
- 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. - + 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. -
-
- 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 requirments without processing the entire - schema and instance documents. + 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. + + - Such implementations MAY chooose 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. + 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. -
-
- -
- - 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). - - + + 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 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 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 requirments without processing the entire + schema and instance documents. + + + Such implementations MAY chooose 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. +
From 04178dab121c13f405c38f314fc8225e72ac8f95 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 13 Oct 2017 12:56:27 -0700 Subject: [PATCH 15/23] Trim down JSON Hyper-Schemas in APIs appendix A lot of this should go on some sort of best practices guide on the web site. This cuts quite a bit of text, and merges the static analysis appendix into the API appendex as API-wide processing is the main use case for such analysis. There is likely more to cut, and perhaps the entire appendix should be removed, but I'd like to get some feedback on this level of information first. --- jsonschema-hyperschema.xml | 121 ++++++++++--------------------------- 1 file changed, 33 insertions(+), 88 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 49cf245e..a92dcd2d 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -13,6 +13,7 @@ + @@ -1347,6 +1348,7 @@ for varname in templateData: &rfc6573; &rfc7230; &rfc7231; + &rfc7807; &I-D.nottingham-rfc5988bis;
@@ -1487,18 +1489,10 @@ for varname in templateData: 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 implement support - for them. 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. - - - JSON Hyper-Schema is ideal for representing individual resources in hypermedia - APIs. It offers comprehensive capabilities for describing how to use hyperlinks - to interact with the current resource (through "self" links), or related - resources. Using a hyper-schema-based API involves traversing links from - one resource to the next, interacting with resources through their - representations as described by the target keywords, or submitting data - to resources for processing using the submission keywords. + 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. Hyper-schema is only concerned with one resource and set of associated links @@ -1508,35 +1502,12 @@ for varname in templateData: any concept of whether or how that resource fits into an API. - While aspects of cross-cutting API concerns such as authentication - and authorization may be described in hyper-schema, for instance in - the headerSchema of a link, defining an API-wide approach to any - cross-cutting concerns is beyond the scope of hyper-schema. + 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. -
- - Working with a JSON Hyper-Schema-based API will generally involve - three components: The hyper-schema implementation, a generic user agent, - and a client application. The hyper-schema implementation's requirements - are given in this specification. The generic user agent handles standardized - URI schemes, protocols, and media types. User agents that handle HTTP, - HTTPS, and JSON, for instance, are available as libraries in many programming - languages. - - - The client application has the domain-specific knowledge of link relation - types and data structure fields needed to make use of the specific API. - A client application can use an available user agent library and a hyper-schema - implementation separately. Alternatively, extensible user agents can allow - adding hyper-schema support as a plug-in alongside support for plain JSON, XML, - or other media types. - - - - Add something about generic user agents not being magic, HATEOAS, etc. - - -
Since a given JSON Hyper-Schema is used with a single resource at a single @@ -1552,29 +1523,6 @@ for varname in templateData: can then make use of the hyper-schema that it recognizes, and ignore newer or older versions. - - Note that this notion of changing the representaiton version using - successive hyper-schemas is separate from deprecating an entire resource - and either removing it or replacing it with a new resource at a new URI. - The "targetHints" keyword can be used to convey deprecation information. - - - - This section is something of a placeholder, with the goal being to - get readers to understand that while hyper-schema helps with versioning, - it does not and will not have explicit features to support it. - - -
-
- - To create an entry point for an API, it is RECOMMENDED to provide - a resource at a documented entry point URI with the minimal amount of data - necessary to begin interacting with API resources. - The hyper-schema for this resource SHOULD contain links to all - API resources that can be accessed with only user input and/or - data contained in the entry point resource's representation. -
@@ -1582,37 +1530,34 @@ for varname in templateData: 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 to allow the user agent or client application to interpret any + 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. + - Protocol and media type specifications provide the necessary information to - deal with different responses at runtime, while documenting all responses - is a concern static analysis across all hyper-schemas making up an API. + 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 +
-
- - 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 - - -
From 315a493a200e70feb4d62e1594d4dccc0133ba9f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 14 Oct 2017 15:15:34 -0700 Subject: [PATCH 16/23] Next hyper-schema draft will be handrews-00 Per discussions with other project members given the rewrite effort. --- jsonschema-hyperschema.xml | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index a92dcd2d..fdf4dbf3 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -26,18 +26,12 @@ - + JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON - -
- aaa@bzfx.net -
- - Cloudflare, Inc.
@@ -45,14 +39,9 @@
- +
- - - Cambridge - UK - - luffgd@gmail.com + aaa@bzfx.net
@@ -1565,7 +1554,7 @@ for varname in templateData: - + From 5872491c2182b07ee75f9a187aa72aec7e7dec90 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 16 Oct 2017 13:22:32 -0700 Subject: [PATCH 17/23] Add output format schema, tidy up other schemas Also improve the wording introducing the output format. Split the "links" fields off from their "required" value, as we may use the format in environments that do not require the same set of fields. For instance, the output format is allowed to omit "href", which is required in an LDO proper. Finally, update the URIs to draft-07-wip which is less confusing than having them say draft-06 (which is blatantly wrong) or draft-07 (which is misleading as it's not yet finalized, much less published). --- hyper-schema-output.json | 61 ++++++++++++++ hyper-schema.json | 10 +-- jsonschema-hyperschema.xml | 18 +++-- links.json | 157 ++++++++++++++++++------------------- schema.json | 4 +- 5 files changed, 159 insertions(+), 91 deletions(-) create mode 100644 hyper-schema-output.json 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 84036996..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": "#"}, @@ -56,7 +56,7 @@ "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-hyperschema.xml b/jsonschema-hyperschema.xml index fdf4dbf3..99187d3f 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -262,10 +262,14 @@ (draft-07 work-in-progress version). - While implementations are free to provide output in any format, the format - used for examples in this document is also used by the conformance test suite, - and is therefore a good default output format. The URI of the JSON Schema - describing that format is + 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 producting output + in this format to faciliated 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). @@ -849,7 +853,7 @@
-
+
At a high level, a conforming implementation will meet the following requirements. Each of these requirements is covered in more detail in the @@ -1218,6 +1222,10 @@ for varname in templateData:
+
+ Examples are being added in a subsequent PR. +
+
Need to reference the core and validation security considerations.
diff --git a/links.json b/links.json index 80f96d2d..1712ef11 100644 --- a/links.json +++ b/links.json @@ -1,86 +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": { - "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-06/hyper-schema#" } - ] - }, - "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" + } } - }, - "templateRequired": { - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - }, - "title": { - "type": "string" - }, - "description": { - "type": "string" - }, - "targetSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "targetMediaType": { - "type": "string" - }, - "targetHints": { }, - "hrefSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "headerSchema": { - "allOf": [ - { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } - ] - }, - "submissionMediaType": { - "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": { From 632a8e1b5c0544e9aa1cec7bc87299df4f4df525 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 17 Oct 2017 11:29:49 -0700 Subject: [PATCH 18/23] Numerous spelling fixes --- jsonschema-hyperschema.xml | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 99187d3f..887dcedd 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -146,7 +146,7 @@ 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 faciliate server push usage. + follow links to facilitate server push usage.
@@ -267,8 +267,8 @@ 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 producting output - in this format to faciliated testing. The URI of the JSON Schema + 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# @@ -372,7 +372,7 @@ 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 construcing a URI based on a URI template + a URI fragment. The process for constructing a URI based on a URI template is given in the URI Templating section.
@@ -501,7 +501,7 @@ 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 resolvling the URI template, with or without client + The full process of resolving the URI template, with or without client input, is covered in the URI Templating section. @@ -521,7 +521,7 @@
- The keywords in this section are used when resolving all URI Tempaltes + 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. @@ -530,7 +530,7 @@ 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" kewyord itself. + not the attachment point of the "base" keyword itself.
@@ -927,7 +927,7 @@ And implementation MUST support looking up links by either their - attachement pointer or context pointer, either by performing the look-up + 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. @@ -1083,7 +1083,7 @@ for varname in T:
- "InputForm" represents whatevers sort of input mechanism is appropriate. + "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. @@ -1209,11 +1209,11 @@ for varname in templateData: 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 requirments without processing the entire + authoritatively fulfill these requirements without processing the entire schema and instance documents. - Such implementations MAY chooose to return non-authoritative answers + 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 @@ -1356,8 +1356,8 @@ for varname in templateData: This appendix provides guidance on how to define links for use with each - common HTTP method, and how collection resources impose additional constarints - on the use of HTTP POST. Additionaly, guidance is provided on hinting at + 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. From 9834381d5cb8bcdf9abebdb443e75838137c7516 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 17 Oct 2017 11:32:58 -0700 Subject: [PATCH 19/23] Move HTTP up between Implementation and Examples While it is technically not a primary part of the specification, but rather an application of the spec to a specific protocol, it is important enough to explaining the motivation and usage of Hyper-Schema to discuss immediately after the general implementation requirements but before the examples. This allows the examples to reference and illustrate HTTP usage. --- jsonschema-hyperschema.xml | 253 +++++++++++++++++++------------------ 1 file changed, 127 insertions(+), 126 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 887dcedd..8637500b 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -1222,132 +1222,6 @@ for varname in templateData:
-
- 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. - -
- - - - - - &rfc2119; - &rfc3986; - - &rfc6570; - &rfc6901; - &I-D.luff-relative-json-pointer; - &I-D.reschke-http-jfv; - - - JSON Schema: A Media Type for Describing JSON Documents - - - - - - - - - - JSON Schema Validation: A Vocabulary for Structural Validation of JSON - - - - - - - - - - &rfc2046; - - &rfc4151; - &rfc5789; - &rfc5988; - &rfc6573; - &rfc7230; - &rfc7231; - &rfc7807; - &I-D.nottingham-rfc5988bis; -
While JSON Hyper-Schema is a hypermedia format and therefore protocol-independent, @@ -1480,6 +1354,133 @@ for varname in templateData:
+ +
+ 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. + +
+ + + + + + &rfc2119; + &rfc3986; + + &rfc6570; + &rfc6901; + &I-D.luff-relative-json-pointer; + &I-D.reschke-http-jfv; + + + JSON Schema: A Media Type for Describing JSON Documents + + + + + + + + + + JSON Schema Validation: A Vocabulary for Structural Validation of JSON + + + + + + + + + + &rfc2046; + + &rfc4151; + &rfc5789; + &rfc5988; + &rfc6573; + &rfc7230; + &rfc7231; + &rfc7807; + &I-D.nottingham-rfc5988bis; +
Hypermedia APIs, which follow the constraints of the REST architectural From 365ef2723df708512ed38104e10e870cb47aab86 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 17 Oct 2017 12:01:42 -0700 Subject: [PATCH 20/23] Wording improvements around HTTP usage. --- jsonschema-hyperschema.xml | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 8637500b..996086ca 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -1251,7 +1251,9 @@ for varname in templateData: All information necessary to use each HTTP method can be conveyed in a - single LDO as explained in this appendix. + 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, @@ -1264,23 +1266,27 @@ for varname in templateData: 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. + 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 - using an entry for the "Accept" request header field in "headerSchema". + 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 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 requests are determined by the "submissionSchema" and + 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. @@ -1350,7 +1356,9 @@ for varname in templateData: 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. + resource to be created to the collection resource. The process for + recognizing collection and item resources is described in + .
From 2706f3e8cb3755180089068a94a7a63ff57f17a0 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 19 Oct 2017 00:26:43 -0700 Subject: [PATCH 21/23] Forgot to change appendix to section --- jsonschema-hyperschema.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 996086ca..79965568 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -1229,7 +1229,7 @@ for varname in templateData: using protocols such as CoAP that are explicitly analogous to HTTP. - This appendix provides guidance on how to define links for use with each + 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 From ef4b0f00c122fc5e4be278cb673e648d1d54f71c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 20 Oct 2017 09:44:31 -0700 Subject: [PATCH 22/23] Forgot to finish sentence Target attributes are advisory, and MUST NOT be considered authoritative. --- jsonschema-hyperschema.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 79965568..87ac0c83 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -565,7 +565,9 @@ 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 + 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.
From 9bfcc5047367aeeac6c6daf2c8b89b6e91aca86e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 20 Oct 2017 10:22:24 -0700 Subject: [PATCH 23/23] Update core change log, rename drafts Needed to add application/schema-instance+json and related changes. --- jsonschema-core.xml | 6 ++++-- jsonschema-validation.xml | 18 +++++++++--------- 2 files changed, 13 insertions(+), 11 deletions(-) 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-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