Skip to content

Commit fa8eb73

Browse files
handrewshandrews
authored
Merge pull request json-schema-org#385 from handrews/aptr
Add "anchorPointer" for in-instance contexts
2 parents 824f1ee + f28d182 commit fa8eb73

File tree

2 files changed

+100
-1
lines changed

2 files changed

+100
-1
lines changed

‎jsonschema-hyperschema.xml

+93-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@
88
<!ENTITY rfc5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml">
99
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
1010
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
11+
<!ENTITY rfc6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
1112
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
13+
<!ENTITY I-D.luff-relative-json-pointer SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-luff-relative-json-pointer-00.xml">
1214
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
1315
]>
1416
<?rfc toc="yes"?>
@@ -654,7 +656,8 @@
654656
resource is the instance to which the schema (or sub-schema)
655657
applies, rather than any larger document in which the
656658
instance may have been found. The context may be changed
657-
with the <xref target="anchor">"anchor"</xref> property.
659+
with the <xref target="anchor">"anchor"</xref> or
660+
<xref target="anchorPointer">"anchorPointer"</xref> properties.
658661
</t>
659662

660663
<t>
@@ -793,6 +796,93 @@ GET /foo/
793796
</t>
794797
</section>
795798

799+
<section title="anchorPointer" anchor="anchorPointer">
800+
<t>
801+
This property changes the point within the instance that is considered
802+
to be the context resource of the link. The value of the property MUST be a
803+
valid <xref target="RFC6906">JSON Pointer</xref>, or a valid
804+
<xref target="I-D.luff-relative-json-pointer">Relative JSON Pointer</xref>
805+
which is evaluated relative to the position in the instance from which
806+
<xref target="href">"href"</xref> template variable resolution would
807+
normally begin.
808+
</t>
809+
<t>
810+
While an alternate context with a known URI is best set with the
811+
<xref target="anchor">"anchor"</xref> keyword, the lack of a fragment identifier
812+
syntax for application/json means that it is usually not possible to
813+
change the context within a JSON instance using a URI.
814+
</t>
815+
<t>
816+
Even in "+json" media types that define JSON Pointer as a fragment identifier
817+
syntax, if the default context is nested within an array, it is not possible to
818+
obtain the index of the default context's position in that array in order
819+
to construct a pointer to another property in that same nested JSON object.
820+
</t>
821+
822+
<figure>
823+
<preamble>
824+
For example, given this hyper-schema:
825+
</preamble>
826+
<artwork>
827+
<![CDATA[{
828+
"type": "object",
829+
"properties": {
830+
"theThing": {
831+
"type": "object",
832+
"properties": {
833+
"name": {"type": "string"}
834+
}
835+
},
836+
"examples": {
837+
"title": "The collection of example for the thing",
838+
"type": "array",
839+
"items": {
840+
"type": "object",
841+
"properties": {
842+
"id": {"type": "integer"}
843+
},
844+
"links": [{
845+
"rel": "item",
846+
"href": "/examples/{id}",
847+
"anchorPointer": "1"
848+
}]
849+
}
850+
}
851+
}
852+
}]]>
853+
</artwork>
854+
<postamble>
855+
The "item" relation indicates that each array entry can be used to construct
856+
a link from the collection embedded in this instance to a resource for that
857+
specific item. The default context of this link is the individual array
858+
element. But the context of an "item" relation should be the collection,
859+
which is the entire "examples" array. The Relative JSON Pointer of "1"
860+
accomplishes this as follows:
861+
</postamble>
862+
</figure>
863+
<figure>
864+
<preamble>
865+
Given this instance of media type application/json:
866+
</preamble>
867+
<artwork>
868+
<![CDATA[{
869+
"theThing": {"name": "An actual thing"},
870+
"examples": [{"id": 1234}, {"id": 5678}]
871+
}]]>
872+
</artwork>
873+
<postamble>
874+
The default context for the link to "/examples/1234" is the first
875+
array entry, and for the link to "/examples/5678" it is the second array
876+
entry. But "anchorPointer" moves this up one instance level (the "1"
877+
Relative JSON Pointer) to be the array containing each entry.
878+
</postamble>
879+
</figure>
880+
<t>
881+
If both "anchor" and "anchorPointer" are defined, and do not resolve to
882+
the same link context, the resulting behavior is undefined.
883+
</t>
884+
</section>
885+
796886
<section title="title">
797887
<t>
798888
This property defines a title for the link.
@@ -1190,6 +1280,8 @@ GET /foo/
11901280
&rfc3986;
11911281
<!--&rfc4287;-->
11921282
&rfc6570;
1283+
&rfc6906;
1284+
&I-D.luff-relative-json-pointer;
11931285
&I-D.reschke-http-jfv;
11941286
<reference anchor="json-schema">
11951287
<front>

‎links.json

+7
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,13 @@
2121
"type": "string",
2222
"format": "uri-reference"
2323
},
24+
"anchorPointer": {
25+
"type": "string",
26+
"anyOf": [
27+
{ "format": "json-pointer" },
28+
{ "pattern": "^[0-9]" }
29+
]
30+
},
2431
"title": {
2532
"type": "string"
2633
},

0 commit comments

Comments
 (0)