Skip to content

Commit 980592e

Browse files
committed
Add guidance on using and creating relation types
Using URIs for custom relation types is often a little intimidating, and frequently ignored. Provide some guidance on some simple approaches to make it easier for hyper-schema authors to use this now-required field correctly.
1 parent c508b71 commit 980592e

File tree

1 file changed

+16
-3
lines changed

1 file changed

+16
-3
lines changed

jsonschema-hyperschema.xml

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
<!ENTITY rfc2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
44
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
55
<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
6+
<!ENTITY rfc4151 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4151.xml">
67
<!--<!ENTITY rfc4287 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml">-->
78
<!--<!ENTITY rfc5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">-->
89
<!ENTITY rfc5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml">
@@ -669,13 +670,24 @@
669670

670671
<t>
671672
Relationship definitions are not normally media type
672-
dependent, and users are encouraged to utilize existing
673-
accepted relation definitions.
673+
dependent, and users are encouraged to utilize the most
674+
suitable existing accepted relation definitions.
674675
</t>
675676

677+
<t>
678+
When no registered relation (aside from "related") applies, users are
679+
encouraged to mint their own extension relation types, as described in
680+
<xref target="RFC5988">section 4.2 of RFC 5988</xref>. The simplest
681+
approaches for choosing link relation type URIs are to either use
682+
a URI scheme that is already in use to identify the system's primary
683+
resources, or to use a human-readable, non-dereferenceable URI scheme
684+
such as <xref target="RFC4151">"tag", defined by RFC 4151</xref>.
685+
Extension relation type URIs need not be dereferenceable, even when
686+
using a scheme that allows it.
687+
</t>
676688
<figure>
677689
<preamble>
678-
For example, if a hyper-schema is defined:
690+
As an example of registered relation types, if a hyper-schema is defined:
679691
</preamble>
680692
<artwork>
681693
<![CDATA[{
@@ -1216,6 +1228,7 @@ GET /foo/
12161228
<references title="Informative References">
12171229
&rfc2046;
12181230
<!--&rfc5226;-->
1231+
&rfc4151;
12191232
&rfc5789;
12201233
&rfc5988;
12211234
&rfc7231;

0 commit comments

Comments
 (0)