Skip to content

Add "anchorPointer" for in-instance contexts #385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 14, 2017
Merged

Add "anchorPointer" for in-instance contexts #385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0c16668
Add "anchorPointer" for in-instance contexts
handrews Aug 31, 2017
a16e917
Integrate "anchor" and "anchorPointer"
handrews Sep 2, 2017
39b1a0b
Add "anchorPointer" to links meta-schema.
handrews Sep 14, 2017
f28d182
Reference JSON Pointer separately
handrews Sep 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 93 additions & 1 deletion jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@
<!ENTITY rfc5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml">
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
<!ENTITY rfc6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
<!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">
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
]>
<?rfc toc="yes"?>
Expand Down Expand Up @@ -654,7 +656,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 <xref target="anchor">"anchor"</xref> property.
with the <xref target="anchor">"anchor"</xref> or
<xref target="anchorPointer">"anchorPointer"</xref> properties.
</t>

<t>
Expand Down Expand Up @@ -793,6 +796,93 @@ GET /foo/
</t>
</section>

<section title="anchorPointer" anchor="anchorPointer">
<t>
This property changes the point within the instance that is considered
to be the context resource of the link. The value of the property MUST be a
valid <xref target="RFC6906">JSON Pointer</xref>, or a valid
<xref target="I-D.luff-relative-json-pointer">Relative JSON Pointer</xref>
which is evaluated relative to the position in the instance from which
<xref target="href">"href"</xref> template variable resolution would
normally begin.
</t>
<t>
While an alternate context with a known URI is best set with the
<xref target="anchor">"anchor"</xref> 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 using a URI.
</t>
<t>
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.
</t>

<figure>
<preamble>
For example, given this hyper-schema:
</preamble>
<artwork>
<![CDATA[{
"type": "object",
"properties": {
"theThing": {
"type": "object",
"properties": {
"name": {"type": "string"}
}
},
"examples": {
"title": "The collection of example for the thing",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "integer"}
},
"links": [{
"rel": "item",
"href": "/examples/{id}",
"anchorPointer": "1"
}]
}
}
}
}]]>
</artwork>
<postamble>
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:
</postamble>
</figure>
<figure>
<preamble>
Given this instance of media type application/json:
</preamble>
<artwork>
<![CDATA[{
"theThing": {"name": "An actual thing"},
"examples": [{"id": 1234}, {"id": 5678}]
}]]>
</artwork>
<postamble>
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.
</postamble>
</figure>
<t>
If both "anchor" and "anchorPointer" are defined, and do not resolve to
the same link context, the resulting behavior is undefined.
</t>
</section>

<section title="title">
<t>
This property defines a title for the link.
Expand Down Expand Up @@ -1190,6 +1280,8 @@ GET /foo/
&rfc3986;
<!--&rfc4287;-->
&rfc6570;
&rfc6906;
&I-D.luff-relative-json-pointer;
&I-D.reschke-http-jfv;
<reference anchor="json-schema">
<front>
Expand Down
7 changes: 7 additions & 0 deletions links.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,13 @@
"type": "string",
"format": "uri-reference"
},
"anchorPointer": {
"type": "string",
"anyOf": [
{ "format": "json-pointer" },
{ "pattern": "^[0-9]" }
]
},
"title": {
"type": "string"
},
Expand Down