From 0c16668be2e1c64e99e17c85b58aedee446e5dbc Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 31 Aug 2017 00:39:55 -0700 Subject: [PATCH 1/4] Add "anchorPointer" for in-instance contexts This will need a bit more work after "anchor" is merged in, as the improved wording about what the default context is is all in that other PR. But the key points are well enough developed for review. In the interst of getting the main points out for review, I referenced the long-expired Relative JSON Pointer I-D. Maybe that's OK since this is not even a working group document yet, or we can talk about how to either move the relevant parts in, or re-submit that I-D ourselves as well. This goes along with "hrefPointers", which adjusts template variable resolution in the same way that this keyword adjusts context location. --- jsonschema-hyperschema.xml | 87 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index d48264a2..63ed4b34 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -9,6 +9,7 @@ + ]> @@ -793,6 +794,91 @@ GET /foo/ +
+ + This property changes the point within the instance that is considered + to be the context resource of the link. The value of the property is a + Relative JSON Pointer, + starting from the default context (the part of the instance that validated + against the schema containing the LDO). + + + 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. + + + 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. + +
+
This property defines a title for the link. @@ -1190,6 +1276,7 @@ GET /foo/ &rfc3986; &rfc6570; + &I-D.luff-relative-json-pointer; &I-D.reschke-http-jfv; From a16e917ac78d0468dde72f9bbc6bfe465ab460be Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 2 Sep 2017 12:23:09 -0700 Subject: [PATCH 2/4] Integrate "anchor" and "anchorPointer" Now that "anchor" has been merged, there are a few points where its text and that of the "anchorPointer" proposal needed adjusting to fit with each other properly. --- jsonschema-hyperschema.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 63ed4b34..9131b3db 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -655,7 +655,8 @@ 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" property. + with the "anchor" or + "anchorPointer" properties. @@ -804,9 +805,9 @@ GET /foo/ While an alternate context with a known URI is best set with the - "anchor" keyword, the lack of a fragment identifier + "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. + change the context within a JSON instance using a URI. Even in "+json" media types that define JSON Pointer as a fragment identifier From 39b1a0b305aaf369d0287096a341d4e025fa5d66 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Sep 2017 19:56:22 -0700 Subject: [PATCH 3/4] Add "anchorPointer" to links meta-schema. --- links.json | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/links.json b/links.json index 76be45b1..00f22a1f 100644 --- a/links.json +++ b/links.json @@ -21,6 +21,13 @@ "type": "string", "format": "uri-reference" }, + "anchorPointer": { + "type": "string", + "anyOf": [ + { "format": "json-pointer" }, + { "pattern": "^[0-9]" } + ] + }, "title": { "type": "string" }, From f28d1825a49fafb9612bfa69995ea29ba119b892 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Sep 2017 20:04:52 -0700 Subject: [PATCH 4/4] Reference JSON Pointer separately Also align the wording around JSON Pointers and Relative JSON Pointers with the wording in the "hrefPointers" specification. --- jsonschema-hyperschema.xml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 9131b3db..658e0371 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -8,6 +8,7 @@ + @@ -798,10 +799,12 @@ GET /foo/
This property changes the point within the instance that is considered - to be the context resource of the link. The value of the property is a - Relative JSON Pointer, - starting from the default context (the part of the instance that validated - against the schema containing the LDO). + 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 @@ -1277,6 +1280,7 @@ GET /foo/ &rfc3986; &rfc6570; + &rfc6906; &I-D.luff-relative-json-pointer; &I-D.reschke-http-jfv;