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"
},