From c508b71c15db07dce38086748f4725caa3694f4a Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 2 Sep 2017 21:28:07 -0700 Subject: [PATCH 1/2] Make "rel" required. RFC 5988bis lists the link relation type as one of the three required aspects of a link. Since we do not need to support the deprecated "rev" mechanisms for specifying relation types, we can make "rel" required. This will encourage hyper-schema authors to think more about choosing relation types. --- jsonschema-hyperschema.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index d48264a2..0145c88d 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -645,6 +645,7 @@ resource. The value MUST be a registered link relation from the IANA Link Relation Type Registry established in RFC 5988, or a normalized URI following the URI production of RFC 3986. + This property is required. From 980592e68e2ccfe67989adff482f09edd18a473f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 2 Sep 2017 21:51:28 -0700 Subject: [PATCH 2/2] 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. --- jsonschema-hyperschema.xml | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 0145c88d..7cb884d0 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -3,6 +3,7 @@ + @@ -669,13 +670,24 @@ Relationship definitions are not normally media type - dependent, and users are encouraged to utilize existing - accepted relation definitions. + dependent, and users are encouraged to utilize the most + suitable existing accepted relation definitions. + + When no registered relation (aside from "related") applies, users are + encouraged to mint their own extension relation types, as described in + section 4.2 of RFC 5988. The simplest + approaches for choosing link relation type URIs are to either use + a URI scheme that is already in use to identify the system's primary + resources, or to use a human-readable, non-dereferenceable URI scheme + such as "tag", defined by RFC 4151. + Extension relation type URIs need not be dereferenceable, even when + using a scheme that allows it. +
- For example, if a hyper-schema is defined: + As an example of registered relation types, if a hyper-schema is defined: &rfc2046; + &rfc4151; &rfc5789; &rfc5988; &rfc7231;