Skip to content
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

Add "hrefPointers" for adjusting resolution #386

Merged
merged 8 commits into from
Sep 15, 2017
Merged

Add "hrefPointers" for adjusting resolution #386

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d1e5e0c
Add "hrefPointers" for adjusting resolution
handrews Aug 31, 2017
96e2290
Fix typos and copy-paste example errors.
handrews Sep 2, 2017
ca608fd
Fix example. Hopefully correctly this time.
handrews Sep 4, 2017
7876b8a
Incorporate review feedback: better example
handrews Sep 12, 2017
77e31f0
Add hrefPointers to links schema.
handrews Sep 13, 2017
fca5fd5
Make it clearer which links are refered at in hrefPointers explanation
Sep 13, 2017
36ed6a1
Cite regular JSON Pointers separately.
handrews Sep 14, 2017
54d22c2
Better meta-schema for hrefPointers
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
126 changes: 124 additions & 2 deletions 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 @@ -358,7 +360,15 @@
<section title="Resolving templated URIs">
<t>
URI Template variables in <xref target="href">"href"</xref> 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.
</t>
<t>
<xref target="hrefPointers">"hrefPointers"</xref> allows adjusting
the location from which instance data is resolved on a per-variable
basis.
</t>
<t>
<xref target="hrefSchema">"hrefSchema"</xref> 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
Expand Down Expand Up @@ -528,7 +538,7 @@
</section>
</section>

<section title="Missing values">
<section title="Missing values" anchor="missingValues">
<t>
Sometimes, the appropriate values will not be available.
For example, the template might specify the use of object properties,
Expand All @@ -548,6 +558,116 @@

</section>

<section title="hrefPointers" anchor="hrefPointers">
<t>
The value of the "hrefPointers" link description property MUST be
an object. Each property value in the object 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>
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.
</t>
<figure>
<preamble>
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.
</preamble>
<artwork>
<![CDATA[{
"type": "object",
"required": ["id"],
"properties": {
"id": {"type": "integer", "minimum": 0},
"children": {"type": "array", "items": {"$ref": "#"}}
},
"links": [
{
"rel": "self",
"href": "/trees/{rootId}/nodes/{id}",
"hrefPointers": {
"rootId": "/id"
}
},
{
"rel": "up",
"href": "/trees/{rootId}/nodes/{parentId}",
"hrefPointers": {
"rootId": "/id",
"parentId": "2/id"
}
}
]
}]]>
</artwork>
</figure>
<t>
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.
</t>
<figure>
<preamble>
Given the following instance:
</preamble>
<artwork>
<![CDATA[{
"id": 0,
"children": [ {
"id": 1,
"children": [ {
"id": 2,
"children": [ {
"id": 3
} ]
} ]
} ]
}]]>
</artwork>
</figure>
<t>
For each node (as identified by JSON Pointers), we get these "self" links:
<list style="hanging">
<t hangText='"" (the root node)'>/trees/0/nodes/0</t>
<t hangText='"/children/0"'>/trees/0/nodes/1</t>
<t hangText='"/children/0/children/0"'>/trees/0/nodes/2</t>
<t hangText='"/children/0/children/0/children/0"'>/trees/0/nodes/3</t>
</list>
</t>
<t>
and these "up" links:
<list style="hanging">
<t hangText='"/children/0"'>/trees/0/nodes/0</t>
<t hangText='"/children/0/children/0"'>/trees/0/nodes/1</t>
<t hangText='"/children/0/children/0/children/0"'>/trees/0/nodes/2</t>
</list>
</t>
<t>
For the root node, the relative pointer for the parent doesn't point
to anything. As noted under
<xref target="missingValues">missing values</xref>, such a link should
simply be ignored.
<cref>
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).
</cref>
</t>
</section>

<section title="hrefSchema" anchor="hrefSchema">
<t>
The value of the "hrefSchema" link description property MUST be
Expand Down Expand Up @@ -1190,6 +1310,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
10 changes: 10 additions & 0 deletions links.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,16 @@
"type": "string",
"format": "uri-template"
},
"hrefPointers": {
"type": "object",
"additionalProperties": {
"type": "string",
"anyOf": [
{ "format": "json-pointer" },
{ "pattern": "^[0-9]" }
]
}
},
"hrefSchema": {
"allOf": [
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
Expand Down