From 2979d0ff86156236e3027f0b438552717982c2d7 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 12 Sep 2017 18:54:37 -0700 Subject: [PATCH 1/3] Control link applicability with hrefRequired This addresses issue #49. Add a keyword, "hrefRequired", that prevents a link from being used if a variable named in that keyword's array cannot be resolved to a value by any available mechanism. Remove outdated language about non-object instances causing problems, as this is addressed by "hrefPointers". --- jsonschema-hyperschema.xml | 73 +++++++++++++++++++++++++------------- links.json | 3 ++ 2 files changed, 52 insertions(+), 24 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 75e836a8..05c41876 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 varibles 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..250ae2c7 100644 --- a/links.json +++ b/links.json @@ -24,6 +24,9 @@ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } ] }, + "hrefRequired": { + "description": "an array of URI template variables names from \"href\" which must be filled out with some value, either from the instance or user input" + }, "rel": { "type": "string" }, From 77df9dfc9cda1a4f63cff51ff06bdb78af28840a Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Sep 2017 23:17:01 -0700 Subject: [PATCH 2/3] Better meta-schema, fix typo. Properly specify the meta-schema, which for some reason was only a description. We don't put descriptions in the meta-schema anymore, but we do put type information. Not sure what happened there. --- jsonschema-hyperschema.xml | 2 +- links.json | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 05c41876..62c3c152 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -537,7 +537,7 @@
Sometimes, the appropriate values will not be available. In many - cases, the URI Template behavior of simply removing varibles that + 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. diff --git a/links.json b/links.json index 250ae2c7..2325317f 100644 --- a/links.json +++ b/links.json @@ -25,7 +25,10 @@ ] }, "hrefRequired": { - "description": "an array of URI template variables names from \"href\" which must be filled out with some value, either from the instance or user input" + "type": "array", + "items": { + "type": "string" + } }, "rel": { "type": "string" From 9a1d8ed49b89f67096bb30c867f75a798cbdad28 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 19 Sep 2017 12:56:17 -0700 Subject: [PATCH 3/3] hrefRequired meta-schema should have uniqueItems --- links.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/links.json b/links.json index 2325317f..f1f32d93 100644 --- a/links.json +++ b/links.json @@ -28,7 +28,8 @@ "type": "array", "items": { "type": "string" - } + }, + "uniqueItems": true }, "rel": { "type": "string"