Skip to content

hrefPointers wording improvements #3

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

Closed
wants to merge 7 commits into from
Closed

hrefPointers wording improvements #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8862129
Add "hrefPointers" for adjusting resolution
handrews Aug 31, 2017
53a3776
Fix typos and copy-paste example errors.
handrews Sep 2, 2017
c982fe0
Fix example. Hopefully correctly this time.
handrews Sep 4, 2017
2559b66
Incorporate review feedback: better example
handrews Sep 12, 2017
4d74bc8
Add hrefPointers to links schema.
handrews Sep 13, 2017
26462c6
Remove spurious "not" 1st hrefPointers example's preamble
Sep 13, 2017
6094c30
Make it clearer which links are refered at in hrefPointers explanation
Sep 13, 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
3 changes: 3 additions & 0 deletions hyper-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,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": {
"description": "a schema for validating user input to the URI template, where the input is in the form of a JSON object with property names matching variable names in \"href\"",
"allOf": [ {"$ref": "#"} ]
Expand Down
124 changes: 122 additions & 2 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
<!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 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">
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
Expand Down Expand Up @@ -488,7 +489,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 @@ -633,7 +642,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 @@ -653,6 +662,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="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, which is 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.
</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 @@ -1181,6 +1300,7 @@ GET /foo/
&rfc3986;
<!--&rfc4287;-->
&rfc6570;
&I-D.luff-relative-json-pointer;
<reference anchor="json-schema">
<front>
<title>JSON Schema: A Media Type for Describing JSON Documents</title>
Expand Down
3 changes: 3 additions & 0 deletions links.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,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": {
"description": "a schema for validating user input to the URI template, where the input is in the form of a JSON object with property names matching variable names in \"href\"",
"allOf": [ {"$ref": "#"} ]
Expand Down