Skip to content

Commit d163932

Browse files
handrewshandrews
authored
Merge pull request json-schema-org#458 from handrews/up-down
Example using "anchor", "base", "templatePointers"
2 parents a251b47 + e785c6d commit d163932

File tree

1 file changed

+108
-10
lines changed

1 file changed

+108
-10
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 108 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1731,7 +1731,7 @@ Link: <https://schema.example.com/entry> rel=describedBy
17311731
},
17321732
"email": false
17331733
}
1734-
}
1734+
},
17351735
"submissionMediaType":
17361736
"multipart/alternative; boundary=ab2",
17371737
"submissionSchema": {
@@ -1802,10 +1802,106 @@ Link: <https://schema.example.com/entry> rel=describedBy
18021802
</list>
18031803
</t>
18041804
</section>
1805-
<section title='"anchor" and "base" as URI Templates'>
1806-
<t><cref>
1807-
"base" used as a template with both "anchor" and "href" templates.
1808-
</cref></t>
1805+
<section title='"anchor", "base" and URI Template resolution'>
1806+
<t>
1807+
A link is a typed connection from a context resource to a target resource.
1808+
Older link serializations support a "rev" keyword that takes a link relation
1809+
type as "rel" does, but reverses the semantics. This has long been deprecated,
1810+
so JSON Hyper-Schema does not support it. Instead, "anchor"'s ability to
1811+
change the context URI can be used to reverse the direction of a link.
1812+
It can also be used to describe a link between two resources, neither of
1813+
which is the current resource.
1814+
</t>
1815+
<t>
1816+
As an example, there is an IANA-registered "up" relation, but
1817+
there is no "down". In an HTTP Link header, you could implement
1818+
"down" as <spanx style="verb">"rev": "up"</spanx>.
1819+
</t>
1820+
<figure>
1821+
<preamble>
1822+
First let's look at how this could be done in HTTP, showing a "self"
1823+
link and two semantically identical links, one with "rev": "up"
1824+
and the other using "anchor" with "rel": "up" (line wrapped due to
1825+
formatting limitations).
1826+
</preamble>
1827+
<artwork>
1828+
<![CDATA[
1829+
GET https://api.example.com/trees/1/nodes/123 HTTP/1.1
1830+
1831+
200 OK
1832+
Content-Type: application/json
1833+
Link: <https://api.example.com/trees/1/nodes/123> rel=self
1834+
Link: <https://api.example.com/trees/1/nodes/123> rel=up
1835+
anchor=<https://api.example.com/trees/1/nodes/456>
1836+
Link: <https://api.example.com/trees/1/nodes/456> rev=up
1837+
{
1838+
"id": 123
1839+
"treeId": 1,
1840+
"childIds": [456]
1841+
}
1842+
]]>
1843+
</artwork>
1844+
<postamble>
1845+
Note that the "rel=up" link has a target URI identical
1846+
to the "rel=self" link, and sets "anchor" (which identifies
1847+
the link's context) to the child's URI. This sort of reversed
1848+
link is easily detectable by tools when a "self" link is also present.
1849+
</postamble>
1850+
</figure>
1851+
1852+
<figure>
1853+
<preamble>
1854+
The following hyper-schema, applied to the instance in the response
1855+
above, would produce the same "self" link and "up" link with "anchor".
1856+
It also shows the use of a templated "base" URI, plus both absolute
1857+
and relative JSON Pointers in "tempaltePointers".
1858+
</preamble>
1859+
<artwork>
1860+
<![CDATA[
1861+
"base": "trees/{treeId}",
1862+
"properties": {
1863+
"id": {"type": "integer"},
1864+
"treeId": {"type": "integer"},
1865+
"childIds": {
1866+
"type": "array",
1867+
"items": {
1868+
"type": "integer",
1869+
"links": [
1870+
{
1871+
"anchor": "nodes/{thisNodeId}",
1872+
"rel": "up",
1873+
"href": "nodes/{childId}",
1874+
"templatePointers": {
1875+
"thisNodeId": "/id",
1876+
"childId": "0"
1877+
}
1878+
}
1879+
]
1880+
}
1881+
}
1882+
},
1883+
"links": [
1884+
{
1885+
"rel": "self",
1886+
"href": "nodes/{id}"
1887+
}
1888+
]
1889+
}]]>
1890+
</artwork>
1891+
<postamble>
1892+
The "base" template is evaluated identically for both the
1893+
target ("href") and context ("anchor") URIs.
1894+
</postamble>
1895+
</figure>
1896+
<t>
1897+
Note the two different sorts of templatePointers used.
1898+
"thisNodeId" is mapped to an absolute JSON Pointer, "/id",
1899+
while "childId" is mapped to a relative pointer, "0", which
1900+
indicates the value of the current item. Absolute
1901+
JSON Pointers do not support any kind of wildcarding, so
1902+
there is no way to specify a concept like "current item"
1903+
without a relative JSON Pointer.
1904+
</t>
18091905
</section>
18101906
<section title="Collections">
18111907
<t><cref>
@@ -1829,8 +1925,8 @@ Link: <https://schema.example.com/entry> rel=describedBy
18291925
</t>
18301926
<t>
18311927
Note that there is an object member called "items", which is an array
1832-
and thefore uses the validation keyword "items" in its own schema. The outer
1833-
"items" is a property name, the inner one is a schema keyword.
1928+
and therefore uses the validation keyword "items" in its own schema.
1929+
The outer "items" is a property name, the inner one is a schema keyword.
18341930
</t>
18351931
<figure>
18361932
<artwork>
@@ -1951,7 +2047,7 @@ Link: <https://schema.example.com/entry> rel=describedBy
19512047
Here are all of the links that apply to this instance,
19522048
including those that are referenced by using the "thing"
19532049
schema for the individual items. The "self" links for
1954-
the overal resource and each individual item are
2050+
the overall resource and each individual item are
19552051
distinguished by different context pointers. Note also
19562052
that the "item" and "self" links for a given thing have
19572053
identical target URIs but different context pointers.
@@ -1962,14 +2058,16 @@ Link: <https://schema.example.com/entry> rel=describedBy
19622058
"contextUri": "https://api.example.com/things",
19632059
"contextPointer": "",
19642060
"rel": "self",
1965-
"targetUri": "https://api.example.com/things?offset=20,limit=2",
2061+
"targetUri":
2062+
"https://api.example.com/things?offset=20,limit=2",
19662063
"attachmentPointer": ""
19672064
},
19682065
{
19692066
"contextUri": "https://api.example.com/things",
19702067
"contextPointer": "",
19712068
"rel": "next",
1972-
"targetUri": "https://api.example.com/things?offset=22,limit=2",
2069+
"targetUri":
2070+
"https://api.example.com/things?offset=22,limit=2",
19732071
"attachmentPointer": ""
19742072
},
19752073
{

0 commit comments

Comments
 (0)