Skip to content

Commit 88747a0

Browse files
handrewshandrews
authored
Merge pull request #386 from handrews/hptr
Add "hrefPointers" for adjusting resolution
2 parents cc3b1ea + 54d22c2 commit 88747a0

File tree

2 files changed

+130
-2
lines changed

2 files changed

+130
-2
lines changed

‎jsonschema-hyperschema.xml

+120-2
Original file line numberDiff line numberDiff line change
@@ -360,7 +360,15 @@
360360
<section title="Resolving templated URIs">
361361
<t>
362362
URI Template variables in <xref target="href">"href"</xref> resolve from
363-
server-supplied instance data by default.
363+
server-supplied instance data by default. This data is drawn from the
364+
sub-instance that validated against the schema containing the LDO.
365+
</t>
366+
<t>
367+
<xref target="hrefPointers">"hrefPointers"</xref> allows adjusting
368+
the location from which instance data is resolved on a per-variable
369+
basis.
370+
</t>
371+
<t>
364372
<xref target="hrefSchema">"hrefSchema"</xref> allows a link to specify
365373
a schema for resolving template variables from client-supplied data.
366374
Regular JSON Schema validation features can be used to require resolution
@@ -530,7 +538,7 @@
530538
</section>
531539
</section>
532540

533-
<section title="Missing values">
541+
<section title="Missing values" anchor="missingValues">
534542
<t>
535543
Sometimes, the appropriate values will not be available.
536544
For example, the template might specify the use of object properties,
@@ -550,6 +558,116 @@
550558

551559
</section>
552560

561+
<section title="hrefPointers" anchor="hrefPointers">
562+
<t>
563+
The value of the "hrefPointers" link description property MUST be
564+
an object. Each property value in the object MUST be a valid
565+
<xref target="RFC6906">JSON Pointer</xref>, or a valid
566+
<xref target="I-D.luff-relative-json-pointer">Relative JSON Pointer</xref>
567+
which is evaluated relative to the position in the instance from which
568+
<xref target="href">"href"</xref> template variable resolution would
569+
normally begin.
570+
</t>
571+
<t>
572+
For each property name in the object that matches a variable name in the
573+
"href" URI Template, the value of that property adjusts the starting position
574+
of variable resolution for that variable. Properties which do not match
575+
"href" template variable names MUST be ignored.
576+
</t>
577+
<figure>
578+
<preamble>
579+
Recall that a Relative JSON Pointer begins with a number indicating
580+
how many levels up to move before applying the remainder of the pointer,
581+
if any, in the same manner as a regular JSON Pointer. Consider the
582+
following schema for n-ary tree nodes, where a node is identified by
583+
its own id as well as the tree's root node id, and links are given for
584+
the IANA-registered "self" and "up" link relation types.
585+
</preamble>
586+
<artwork>
587+
<![CDATA[{
588+
"type": "object",
589+
"required": ["id"],
590+
"properties": {
591+
"id": {"type": "integer", "minimum": 0},
592+
"children": {"type": "array", "items": {"$ref": "#"}}
593+
},
594+
"links": [
595+
{
596+
"rel": "self",
597+
"href": "/trees/{rootId}/nodes/{id}",
598+
"hrefPointers": {
599+
"rootId": "/id"
600+
}
601+
},
602+
{
603+
"rel": "up",
604+
"href": "/trees/{rootId}/nodes/{parentId}",
605+
"hrefPointers": {
606+
"rootId": "/id",
607+
"parentId": "2/id"
608+
}
609+
}
610+
]
611+
}]]>
612+
</artwork>
613+
</figure>
614+
<t>
615+
In "self" link, the context node's id resolves with the standard process and
616+
therefore does not appear in "hrefPointers". In both "self" and "up" links,
617+
the root id is located using an absolute JSON Pointer. Finally, in "up" link,
618+
the parent node uses a Relative JSON Pointer, going up two levels (one level up
619+
is the array of children, two levels up is the whole parent node), and then
620+
looking at the "id" field from that point.
621+
</t>
622+
<figure>
623+
<preamble>
624+
Given the following instance:
625+
</preamble>
626+
<artwork>
627+
<![CDATA[{
628+
"id": 0,
629+
"children": [ {
630+
"id": 1,
631+
"children": [ {
632+
"id": 2,
633+
"children": [ {
634+
"id": 3
635+
} ]
636+
} ]
637+
} ]
638+
}]]>
639+
</artwork>
640+
</figure>
641+
<t>
642+
For each node (as identified by JSON Pointers), we get these "self" links:
643+
<list style="hanging">
644+
<t hangText='"" (the root node)'>/trees/0/nodes/0</t>
645+
<t hangText='"/children/0"'>/trees/0/nodes/1</t>
646+
<t hangText='"/children/0/children/0"'>/trees/0/nodes/2</t>
647+
<t hangText='"/children/0/children/0/children/0"'>/trees/0/nodes/3</t>
648+
</list>
649+
</t>
650+
<t>
651+
and these "up" links:
652+
<list style="hanging">
653+
<t hangText='"/children/0"'>/trees/0/nodes/0</t>
654+
<t hangText='"/children/0/children/0"'>/trees/0/nodes/1</t>
655+
<t hangText='"/children/0/children/0/children/0"'>/trees/0/nodes/2</t>
656+
</list>
657+
</t>
658+
<t>
659+
For the root node, the relative pointer for the parent doesn't point
660+
to anything. As noted under
661+
<xref target="missingValues">missing values</xref>, such a link should
662+
simply be ignored.
663+
<cref>
664+
GitHub issue #49 tracks the question of distinguishing this situation
665+
of a missing required variable (common in path components) from
666+
missing optional variables (common in query string parameters).
667+
</cref>
668+
</t>
669+
</section>
670+
553671
<section title="hrefSchema" anchor="hrefSchema">
554672
<t>
555673
The value of the "hrefSchema" link description property MUST be

‎links.json

+10
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,16 @@
99
"type": "string",
1010
"format": "uri-template"
1111
},
12+
"hrefPointers": {
13+
"type": "object",
14+
"additionalProperties": {
15+
"type": "string",
16+
"anyOf": [
17+
{ "format": "json-pointer" },
18+
{ "pattern": "^[0-9]" }
19+
]
20+
}
21+
},
1222
"hrefSchema": {
1323
"allOf": [
1424
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }

0 commit comments

Comments
 (0)