From d1e5e0c037578df3e5277b9e0db06fb6f97b4a3f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 31 Aug 2017 09:28:49 -0700 Subject: [PATCH 1/8] Add "hrefPointers" for adjusting resolution This is a companion to "anchorPointer", as they use the same mechanism for adjusting locations within the instance. While "anchorPointer" adjusts the context, "hrefPointers" adjust how template variables are resolved. "hrefPointers" replaces and is much more functional than the preprocessing rules that were removed in draft wright-01. Those rules only allowed adjusting to use the sub-instance as a whole intead of individual properties or elements. "hrefPointers" supports that as well as using data from any containg or sub-instance. --- jsonschema-hyperschema.xml | 90 +++++++++++++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index d48264a2..0fb703ac 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -9,6 +9,7 @@ + ]> @@ -358,7 +359,15 @@
URI Template variables in "href" resolve from - server-supplied instance data by default. + server-supplied instance data by default. This data is drawn from the + sub-instance that validated against the schema containing the LDO. + + + "hrefPointers" allows adjusting + the location from which instance data is resolved on a per-variable + basis. + + "hrefSchema" allows a link to specify a schema for resolving template variables from client-supplied data. Regular JSON Schema validation features can be used to require resolution @@ -548,6 +557,84 @@
+
+ + The value of the "hrefPointers" link description property MUST be + an object. Each property value in the object MUST be a valid + Relative JSON Pointer, + which is evaluated relative to the position in the instance from which + "href" template variable resolution would + normolly begin. + + + For each property name in the object that matches a variable name in the + "href" URI Template, the value of that property adjusts the starting position + of variable resolution for that variable. Properties which do not match + "href" template variable names MUST be ignored. + +
+ + Consider the following schema for an n-ary tree using the path expansion + URI Template syntax: + + + + + + The self links here should always include the root node id, + followed by an immediate parent id if one exists, and always ending + with the id of the node that is the context of the self link. + +
+
+ + Given the following instance: + + + + +
+ + We get the following self links for each node in the instance as identifed + by JSON Pointers: + + /trees/0/0 + /trees/0/0/1 + /trees/0/1/2 + /trees/2/3 + + omitted, giving us the desired URI with two components after "/trees". The + This shows the use of an absolute JSON Pointer to always resolve + the root node from any depth, and a Relative JSON Pointer to always resolve + the immediate parent, which cannot be identified with an absolute pointer. + For the root node, there is no defined parent, so per URI Template resolution + rules, that variable and the path component that it would produce are simply + omitted, giving us the desired URI with two components after "/trees". + +
+
The value of the "hrefSchema" link description property MUST be @@ -1190,6 +1277,7 @@ GET /foo/ &rfc3986; &rfc6570; + &I-D.luff-relative-json-pointer; &I-D.reschke-http-jfv; From 96e229041eae8dc689724cb08ff14ad4aa36690b Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 2 Sep 2017 01:24:48 -0700 Subject: [PATCH 2/8] Fix typos and copy-paste example errors. --- jsonschema-hyperschema.xml | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 0fb703ac..ae1b47b9 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -564,7 +564,7 @@ Relative JSON Pointer, which is evaluated relative to the position in the instance from which "href" template variable resolution would - normolly begin. + normally begin. For each property name in the object that matches a variable name in the @@ -590,6 +590,9 @@ "rel": "self", "href": "/trees{/root,parent,id}" "hrefPointers": { + "root": "/id", + "parent": "2/id" + } } ] }]]> @@ -598,6 +601,11 @@ The self links here should always include the root node id, followed by an immediate parent id if one exists, and always ending with the id of the node that is the context of the self link. + The context node's id resolves with the standard process and + does not appear in "hrefPointers". The root id is located + using an absolute JSON Pointer, while 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).
@@ -623,9 +631,8 @@ /trees/0/0 /trees/0/0/1 /trees/0/1/2 - /trees/2/3 + /trees/0/2/3 - omitted, giving us the desired URI with two components after "/trees". The This shows the use of an absolute JSON Pointer to always resolve the root node from any depth, and a Relative JSON Pointer to always resolve the immediate parent, which cannot be identified with an absolute pointer. From ca608fdbef7f3793b68a432ac325a0acdd1a1577 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 4 Sep 2017 10:21:48 -0700 Subject: [PATCH 3/8] Fix example. Hopefully correctly this time. Also note limitations of the hrefPointer system. --- jsonschema-hyperschema.xml | 45 +++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index ae1b47b9..4b93c3e4 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -588,7 +588,7 @@ "links": [ { "rel": "self", - "href": "/trees{/root,parent,id}" + "href": "/trees{/root,parent,id}", "hrefPointers": { "root": "/id", "parent": "2/id" @@ -597,17 +597,27 @@ ] }]]> - - The self links here should always include the root node id, - followed by an immediate parent id if one exists, and always ending - with the id of the node that is the context of the self link. - The context node's id resolves with the standard process and - does not appear in "hrefPointers". The root id is located - using an absolute JSON Pointer, while 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). -
+ + The self links here should always include the root node id, + followed by an immediate parent id if one exists, and always ending + with the id of the node that is the context of the self link. + + + The context node's id resolves with the standard process and + does not appear in "hrefPointers". The root id is located + using an absolute JSON Pointer, while 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). + + + This design never has more than three ids in the URI. Nodes + along the path between the root and the immediate parent, + if any, are omitted. This illustrates a limitation of JSON Schema: + Producing a variable-length path URI to any arbitrary depth is + not possible without redesigning the representation to make an + array of path ids available in each node. +
Given the following instance: @@ -621,7 +631,10 @@ "id": 2, "children": [ { "id": 3 -} ] } ] } ] }]]> + } ] + } ] + } ] +}]]>
@@ -629,13 +642,15 @@ by JSON Pointers: /trees/0/0 - /trees/0/0/1 - /trees/0/1/2 - /trees/0/2/3 + /trees/0/0/1 + /trees/0/1/2 + /trees/0/2/3 This shows the use of an absolute JSON Pointer to always resolve the root node from any depth, and a Relative JSON Pointer to always resolve the immediate parent, which cannot be identified with an absolute pointer. + + For the root node, there is no defined parent, so per URI Template resolution rules, that variable and the path component that it would produce are simply omitted, giving us the desired URI with two components after "/trees". From 7876b8a268bc3b898aa3c5126c995e236cc11b94 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 12 Sep 2017 11:29:45 -0700 Subject: [PATCH 4/8] Incorporate review feedback: better example This example simplifies the concepts by getting rid of the confusing variable-length URIs and just acknowledging that the parent URI for the root node does not make any sense. This sort of situation is addressed elsewhere in the spec, so add an xref to it. The reworked example uses two links: one to illustrate standard resolution (not appearing in "hrefPointers") alongside of an "hrefPointers" adjustment using an absolute pointer, and then another illustratig both absolute and relative pointers. --- jsonschema-hyperschema.xml | 76 +++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 33 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 4b93c3e4..1d395ff2 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -537,7 +537,7 @@
-
+
Sometimes, the appropriate values will not be available. For example, the template might specify the use of object properties, @@ -574,8 +574,13 @@
- Consider the following schema for an n-ary tree using the path expansion - URI Template syntax: + Recall that a Relative JSON Pointer which is not also a regular + 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.
- - The self links here should always include the root node id, - followed by an immediate parent id if one exists, and always ending - with the id of the node that is the context of the self link. - The context node's id resolves with the standard process and - does not appear in "hrefPointers". The root id is located + therefore does not appear in "hrefPointers". The root id is located using an absolute JSON Pointer, while 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). - - - This design never has more than three ids in the URI. Nodes - along the path between the root and the immediate parent, - if any, are omitted. This illustrates a limitation of JSON Schema: - Producing a variable-length path URI to any arbitrary depth is - not possible without redesigning the representation to make an - array of path ids available in each node. + is the array of children, two levels up is the whole parent node), + and then looking at the "id" field from that point.
@@ -638,22 +638,32 @@
- We get the following self links for each node in the instance as identifed - by JSON Pointers: + For each node (as identified by JSON Pointers), we get these "self" links: - /trees/0/0 - /trees/0/0/1 - /trees/0/1/2 - /trees/0/2/3 + /trees/0/nodes/0 + /trees/0/nodes/1 + /trees/0/nodes/2 + /trees/0/nodes/3 - This shows the use of an absolute JSON Pointer to always resolve - the root node from any depth, and a Relative JSON Pointer to always resolve - the immediate parent, which cannot be identified with an absolute pointer. - For the root node, there is no defined parent, so per URI Template resolution - rules, that variable and the path component that it would produce are simply - omitted, giving us the desired URI with two components after "/trees". + 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. 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). +
From 77e31f0cb262ba0568e99d942327688cd2a61bb0 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 12 Sep 2017 17:49:20 -0700 Subject: [PATCH 5/8] Add hrefPointers to links schema. --- links.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/links.json b/links.json index 76be45b1..eaf039d4 100644 --- a/links.json +++ b/links.json @@ -9,6 +9,9 @@ "type": "string", "format": "uri-template" }, + "hrefPointers": { + "description": "a map of variable names to relative instance JSON Pointers, which adjust the instance location from which template variable resolution begins" + }, "hrefSchema": { "allOf": [ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } From fca5fd50e9ac64067ca6a0bba5a0807434711973 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Wed, 13 Sep 2017 09:48:45 +0200 Subject: [PATCH 6/8] Make it clearer which links are refered at in hrefPointers explanation --- jsonschema-hyperschema.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 1d395ff2..3a91cd7d 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -611,12 +611,12 @@ - The context node's id resolves with the standard process and - therefore does not appear in "hrefPointers". The root id is located - using an absolute JSON Pointer, while 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. + In "self" link, the context node's id resolves with the standard process and + therefore does not appear in "hrefPointers". 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.
From 36ed6a19b14b1132779d5d9991c619fd8131c9c9 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Sep 2017 19:44:39 -0700 Subject: [PATCH 7/8] Cite regular JSON Pointers separately. --- jsonschema-hyperschema.xml | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 3a91cd7d..ec954021 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -8,6 +8,7 @@ + @@ -561,7 +562,8 @@ The value of the "hrefPointers" link description property MUST be an object. Each property value in the object MUST be a valid - Relative JSON Pointer, + 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. @@ -574,13 +576,12 @@
- Recall that a Relative JSON Pointer which is not also a regular - 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. + 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. &rfc6570; + &rfc6906; &I-D.luff-relative-json-pointer; &I-D.reschke-http-jfv; From 54d22c2598ab2d1153af139191e28f61fd3d3a77 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Sep 2017 19:47:24 -0700 Subject: [PATCH 8/8] Better meta-schema for hrefPointers Specify the actual object and property types, and drop the description as we no longer keep those in the meta-schema. --- links.json | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/links.json b/links.json index eaf039d4..286309e1 100644 --- a/links.json +++ b/links.json @@ -10,7 +10,14 @@ "format": "uri-template" }, "hrefPointers": { - "description": "a map of variable names to relative instance JSON Pointers, which adjust the instance location from which template variable resolution begins" + "type": "object", + "additionalProperties": { + "type": "string", + "anyOf": [ + { "format": "json-pointer" }, + { "pattern": "^[0-9]" } + ] + } }, "hrefSchema": { "allOf": [