Skip to content

Commit 8db24a2

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 9d39762 commit 8db24a2

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
@@ -4,6 +4,7 @@
44
<!ENTITY rfc2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
55
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
66
<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
7+
<!ENTITY rfc4151 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4151.xml">
78
<!--<!ENTITY rfc4287 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml">-->
89
<!--<!ENTITY rfc5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">-->
910
<!ENTITY rfc5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml">
@@ -782,13 +783,24 @@
782783

783784
<t>
784785
Relationship definitions are not normally media type
785-
dependent, and users are encouraged to utilize existing
786-
accepted relation definitions.
786+
dependent, and users are encouraged to utilize the most
787+
suitable existing accepted relation definitions.
787788
</t>
788789

790+
<t>
791+
When no registered relation (aside from "related") applies, users are
792+
encouraged to mint their own extension relation types, as described in
793+
<xref target="RFC5988">section 4.2 of RFC 5988</xref>. The simplest
794+
approaches for choosing link relation type URIs are to either use
795+
a URI scheme that the system is already using to identify its primary
796+
resources, or to use a human-readable, no-dereferenceable URI scheme
797+
such as <xref target="RFC4151">"tag", defined by RFC 4151</xref>.
798+
Extension relation type URIs need not be dereferenceable, even when
799+
using a scheme that allows it.
800+
</t>
789801
<figure>
790802
<preamble>
791-
For example, if a hyper-schema is defined:
803+
As an example of registered relation types, if a hyper-schema is defined:
792804
</preamble>
793805
<artwork>
794806
<![CDATA[{
@@ -1252,6 +1264,7 @@ GET /foo/
12521264
<references title="Informative References">
12531265
&rfc2046;
12541266
<!--&rfc5226;-->
1267+
&rfc4151;
12551268
&rfc5789;
12561269
&rfc5988;
12571270
&rfc7231;

0 commit comments

Comments
 (0)