diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 75e836a8..62c3c152 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -172,12 +172,6 @@ This example schema defines the properties of the instance as well as link relations for the instance, with URIs incorporating values from the instance. - - "id" probably should not normally be a required keyword, since new instances - will have an unknown "id" property until is it assigned by the server. - However, this property is used in a link, and without it, multiple different - instances would be given the same rel=self URI! - @@ -542,18 +536,23 @@
- Sometimes, the appropriate values will not be available. - For example, the template might specify the use of object properties, - but no such data was provided (or "hrefSchema" is not present), and the - instance is an array or a string. + Sometimes, the appropriate values will not be available. In many + cases, the URI Template behavior of simply removing variables that + do not have a value will be appropriate. An example of this is + optional query parameters, the presence or absence of which does + not change the nature of the link relation type. - If any of the values required for the template are neither present in - the user agent data (if relevant) nor the JSON instance, then substitute - values MAY be provided from another source (such as default values). - Otherwise, the link definition SHOULD be considered not to apply to the - instance. + However, some variables, such as an identifier used in a path component, + cannot meaningfully be omitted. The resulting URI would be meaningless, + or would require a different link relation type. While "hrefSchema" can + express a requirement for those variables that can be supplied via input, + some variables must be resolved from instance data. When that instance + data is not required by the context schema, the + "hrefRequired keyword may be used to + indicate that when the instance data is not available, the link does + not apply.
@@ -607,7 +606,8 @@ "hrefPointers": { "rootId": "/id", "parentId": "2/id" - } + }, + "hrefRequired": ["parentId"] } ] }]]> @@ -659,14 +659,8 @@ For the root node, the relative pointer for the parent doesn't point - to anything. As noted under - missing values, such a link should - simply be ignored. - - GitHub issue #49 tracks the question of distinguishing this situation - of a missing required variable (common in path components) from - missing optional variables (common in query string parameters). - + to anything, so "hrefRequired" + prevents the link from being used with that node. @@ -761,6 +755,37 @@ +
+ + 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 + "hrefPointers 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 "hrefRequired" 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 diff --git a/links.json b/links.json index a02f3382..f1f32d93 100644 --- a/links.json +++ b/links.json @@ -24,6 +24,13 @@ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } ] }, + "hrefRequired": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, "rel": { "type": "string" },