Merge pull request #213 from alien-mcl/issue/208_Relative_template_Uris

Relative Template URIs
HydraCG · Sep 20, 2020 · 3d6d1f6 · 3d6d1f6
2 parents b6157a5 + e40f45d
commit 3d6d1f6
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 1 deletion.
diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld
@@ -544,6 +544,36 @@
       "range": "xsd:string",
       "vs:term_status": "testing"
     },
+    {
+      "@id": "hydra:resolveRelativeUsing",
+      "@type": "rdf:Property",
+      "label": "relative Uri resolution",
+      "domain": "hydra:IriTemplate",
+      "range": "hydra:BaseUriSource",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:BaseUriSource",
+      "@type": "hydra:Class",
+      "subClassOf": "hydra:Resource",
+      "label": "Base Uri source",
+      "comment": "Provides a base abstract for base Uri source for Iri template resolution.",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:Rfc3986",
+      "@type": "hydra:BaseUriSource",
+      "label": "RFC 3986 based",
+      "comment": "States that the base Uri should be established using RFC 3986 reference resolution algorithm specified in section 5.",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:LinkContext",
+      "@type": "hydra:BaseUriSource",
+      "label": "Link context",
+      "comment": "States that the link's context IRI, as defined in RFC 5988, should be used as the base Uri",
+      "vs:term_status": "testing"
+    },
     {
       "@id": "hydra:offset",
       "@type": "rdf:Property",

diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html
@@ -1166,7 +1166,43 @@ <h3>Templated Links</h3>
       <li>resource <i>http://api.example.com/events</i> should not have an Iri template exposed as there
         are no additional details available, neither in the initial resources' payload nor in the API documentation.</li>
     </ul>
-  </section>
+
+    <p>IRI expansion should be performed with respect to the specification
+      behind the IRI template type (RFC 6570 by default), and the product
+      of this process SHOULD be an IRI. When the produced IRI is relative,
+      a case client SHOULD stick to RFC 3986 sections 5.1.3 and 5.1.4 to be compatible
+      with most RDF serializations that support relative IRIs. Still, it may be
+      preferred to use another base URI for the expansion process, which
+      makes a <i>resolveRelativeTo</i> term useful. It allows to switch the
+      IRI template expansion algorithm so the base URI is established using
+      current link context, which is a subject of the relation pointing to an
+      <i>IriTemplate</i> instance. In case that subject is a relative URI,
+      default behavior SHOULD be used as fallback.</p>
+
+    <p>The example below allows to make the product of an IRI template
+      expansion relative to the <i>http://api.example.com/an-issue/</i> resource
+      by using it as its base URI, which further enables the <i>some:operation</i> to
+      be moved to i.e. API documentation level rather to inline it.</p>
+
+    <pre class="example nohighlight"
+         data-transform="updateExample"
+         title="Custom base Uri resolution for an Iri template">
+      <!--
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/an-issue/",
+        "@type": "Collection",
+        "some:operation": {
+          "@type": "IriTemplate",
+          "template": "/{id}",
+          "resolveRelativeTo": "LinkContext",
+          "variable": "id",
+          "mapping": {...}
+        }
+      }
+      -->
+    </pre>
+</section>
 
   <section>
     <h3>Description of HTTP Status Codes and Errors</h3>