links+json.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC6838 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6838.xml">
<!ENTITY RFC7230 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7230.xml">
<!ENTITY RFC7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
<!ENTITY RFC8259 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8259.xml">
<!ENTITY RFC8288 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8288.xml">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?> <!-- used by XSLT processors -->
<!-- OPTIONS, known as processing instructions (PIs) go here. -->
<!-- For a complete list and description of PIs,
     please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable PIs that most I-Ds might want to use. -->
<?rfc strict="yes" ?> <!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC): -->
<?rfc toc="yes"?> <!-- generate a ToC -->
<?rfc tocdepth="2"?> <!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references: -->
<?rfc symrefs="yes"?> <!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?> <!-- sort the reference entries alphabetically -->
<!-- control vertical white space: 
     (using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?> <!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?> <!-- keep one blank line between list items -->
<!-- end of popular PIs -->
<rfc  category="std" docName="draft-wparad-json-links-03" ipr="trust200902">
  <front>
    <title abbrev="Links+JSON">JSON Hypermedia Links Notation</title>
    <author fullname="Warren Parad" initials="W" surname="Parad">
<!-- <organization/> -->
      <address>
        <!-- postal><street/><city/><region/><code/><country/></postal -->
<!-- <phone/> -->
<!-- <facsimile/> -->
      <email>rfc@warrenparad.net</email>
<!-- <uri/> -->
      </address>
    </author>
    <author fullname="Igor Sowinski" initials="I" surname="Sowinski">
<!-- <organization/> -->
      <address>
        <!-- postal><street/><city/><region/><code/><country/></postal -->
<!-- <phone/> -->
<!-- <facsimile/> -->
      <email>igorsowinski.mail@gmail.com</email>
<!-- <uri/> -->
      </address>
    </author>
    <author fullname="Rafal Nowosielski" initials="R" surname="Nowosielski">
      <!-- <organization/> -->
      <address>
        <!-- postal><street/><city/><region/><code/><country/></postal -->
        <!-- <phone/> -->
        <!-- <facsimile/> -->
        <email>rafal@nowosielski.email</email>
        <!-- <uri/> -->
      </address>
    </author>
    <date year="2018" />
<!-- <area/> -->
<!-- <workgroup/> -->
      <keyword>Hypermedia</keyword>
      <keyword>Web Linking</keyword>
      <keyword>links+json</keyword>
       <keyword>json+links</keyword>
<!-- <keyword/> -->
    <abstract>
      <t>
        This document proposes the application/links+json media type for representing resources and their relations with hyperlinks. It treats hypermedia links as first class object which can appear throughout a JSON document.
      </t>
    </abstract>
  </front>
  <middle>
    <section title="Introduction">
      <t>
        This document introduces the media type "application/links+json" to support hypermedia linking inside JSON as defined by <xref target="RFC6838"/> and <xref target="RFC8259"/>.  Hypermedia linking provides a dynamic way to navigate from one JSON representation to another JSON representation by following a URI in the form of a navigatable URL.  To ensure URLs are discoverable this standard creates the notion of a first class "links" JSON object name.  This property MUST adhere to the format in this document, and provides an a priori discoverability to representations which are of the media type "application/links+json".
      </t>
      <t>
        The "links" JSON object name becomes a reserved word and cannot be used without implying the semantics of this document.  The "links" can be found at multiple depths of a JSON representation and always implying the same meaning with regards to the context.  It is a dictionary which provides <xref target="RFC8288">web linking</xref> by defining the semanitcs of a linked representation.
      </t>
      <t>
        The design of "application/links+json" proposes a straightforward model which combines the simplicity of JSON object with a predefined "links" structure.
      </t>
      <t>
        This document is being discussed in the <eref target="https://gitter.im/wparad/draft-wparad-json-links">draft-wparad-json-links Gitter room</eref>.
      </t>
    </section>
    <section title="Terminology">  
      <t>
        The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
        this document are to be interpreted as described in
        <xref target="RFC2119"/>.
      </t>
      <t>
        Following the JSON standard conventions defined in <xref target="RFC8259"/>, the Links Notation will define specific definitions to each of the follow terms, as they are reused through the document.
      </t>
      <section title="Link-Relation">
      <t>
        Also known as <xref target="RFC8288">web linking</xref>, is the relationship between the current JSON resource representation and a related one.  The related resource can be discovered by navigating from the representation through the "links" object to the "href" of the relevant "rel".
      </t>
      </section>
      <section title="Links">
        <t>
          The "links" JSON name or hereafter called "links" property is the JSON property name "links" and the associated "links" property value object.  The property object will be known as the "links" object.  The property name MUST be "links", and is a reserved word.
        </t>
      </section>
      <section title="JSON Link Property Name">
        <t>
          The "links" object contains a set of JSON name properties, each of these properties will be known simply as a "link".  Its JSON property name may be anything other than "links", including the value "link".  The JSON property value of the "link", is a "Link Object".  The property name is unique value within all the "links" objects in the whole JSON document.
        </t>
      </section>
      <section title="JSON Link Property Value Object">
        <t>
          The Link Value Object is the JSON value object which is the member value for the JSON property defined by a "link" property.  It is a "resource" link relation used to navigate to another hypermedia link.
        </t>
      </section>
    </section>
    <section title="Reserved Words">
      <t>
        The application/links+json reserves the following words which maintain their definition and no other value can replace them.  The are as follows:
        <list>
          <t>* "links": any other value will assume its meaning from the media type of the JSON body representation, except for the reserved word "links".  "links" has the semantic meaning as defined by this document.</t>
        </list>
      </t>
    </section>
    <section title="Links Notation Document">
      <t>
        A JSON Links Document uses the format described in <xref target="RFC8259"/> and has the media type "application/links+json".  The media type provides a polymorphic transform on JSON and introduces only a Hypermedia Links Notation for expanding a "links" object value.  Therefore "application/links+json" is of media type "application/json".
      </t>
      <t>
        The "links" object in a JSON object.  The object contains "link" properties which each uniquely define a related resource.  The JSON values associated with those names MUST be a JSON object which explain how to navigate to that resource.
      </t>
    </section>
    <section title="Link Resources">
      <t>
        Each JSON "link" name specified in the "links" object is a link relation and the related representation resource MUST be a different hypermedia resource.  Additionally, each "resource" or "link" MUST be a JSON object which contains ONLY these predefined fields.
      </t>
      <section title="rel">
        <t>
          The "rel" JSON name is OPTIONAL when the "link" property name is a link relation per <xref target="RFC8288"/>, if not, then the "rel" property MUST be provided.  The "rel" MUST be either an "absolute-URI" or a predefined link relation.
        </t>
        <t>
          When not defined the link relation is assumed from the "link" JSON object name.  To provide conformant JSON property names, the "rel" JSON name can be used, and an improved "link" JSON object name can be provided as the "link" property name.  The "rel" context applies to the relation of the immediate links object which contains it.  The "self" link relation inside a nested "links" object provides a different semantic meaning then the "self" link relation inside a "links" object specified at the top level of a resource object.  Link relations apply to the context that link relation is found within.  This means that the same link relation MAY be present in a JSON representation multiple times and each it SHOULD specify a different "href".
        </t>
      </section>
      <section title="href">
        <t>
          The "href" JSON name MUST be provided and defines a the URL for a resource and MUST be an "absolute-URI" per <xref target="RFC7230"/>.  When not defined the link relation is assumed from the "link" JSON object name.
        </t>
      </section>
      <section title="templates">
        <t>
          The "templates" JSON name SHOULD be provided.  When present it shows the semantics on how to follow the defined the URL specified in the "href" property.  The "templates" JSON value is a JSON object.  The JSON property names of the JSON object MUST be HTTP method verbs as defined by <xref target="RFC7231"/>.  When not provided, the implicit default is that only GET is supported. The JSON property value of each of these templated verbs contains the following fields:
          <list>
            <t>
              * "type": OPTIONAL, Type is the media type or documentation URL location which points to the documented semantics of the type required to follow the link.  When the verb is "GET", the "type" field MUST NOT be provided.  When the type is not a media type, the documentation location URL is specified the location must point to either to the semantics of the object or an <eref target="https://github.com/OAI/OpenAPI-Specification">Open API Schema</eref> object.
            </t>
          </list>
        </t>
      </section>
    </section>
    <section title="Discoverability">
      <t>
        To ensure discoverability and meaning to each link relation in a "links" object. Each "links" object MUST be specified at with the most specific child JSON object value as relates to the link relation.  When a JSON property name "item" exists and a "link" to that "item" needs to be specified, the "link" should contain a "self" and be present inside the "item" JSON object value.  The "item" link SHALL NOT be provided in the top most "link" object.  The "item" "link" SHALL NOT be specified in a top level "links" object which contains a link relation name "item" and a "rel" https://example.org/rels/v1/item.
      </t>
      <t>
        If no JSON property with the "item" property name exists, then the "item" SHALL be added to the "links" object at the top level.  Once this link is located here, a JSON property "item" MUST NOT be created in the representation.
      </t>
    </section>
    <section title="Links Example">
      <t>
        Here is an example:
        <figure>
          <artwork>
            <![CDATA[
{
  "resourceId": "123",
  "other_resource": {
    "otherResourceId": "abc",
    "links": {
      "self": {
        "href": "https://example.org/v1/resources/abc",
        "templates": {
          "GET": {}
        }
      },
      "create": {
        "rel": "https://example.org/rels/v1/create",
        "href": "https://example.org/v1/other_resources",
        "templates": {
          "POST": {
            "type": "https://example.org/rels/v1/other_resources"
          }
        }
      }
    }
  },
  "links": {
    "self": {
      "href": "https://example.org/v1/resources/123",
      "templates": {
        "GET": {}
      }
    },
    "hypermedia_other_relation": {
      "rel": "https://example.org/rels/v1/hypermedia_other_relation",
      "href": "https://example.org/resources/456",
      "templates": {
        "GET": {}
      }
    }
  }
}
            ]]>
          </artwork>
        </figure>
      </t>
      <t>
        To include a collection of links, it MUST be presented as a first class JSON array of JSON objects.  Each object containing its own "links" object:
        <figure>
          <artwork>
            <![CDATA[
{
  "collectionId": "collection-1",
  "resourceCollection": [
    {
      "itemId": "item-1",
      "links": {
        "self": {
          "href": "https://example.org/v1/items/item-1"
        }
      }
    },
    {
      "itemId": "item-2",
      "links": {
        "self": {
          "href": "https://example.org/v1/items/item-2"
        }
      }
    }
  ],
  "links": {
    "self": {
      "href": "https://example.org/v1/collections/collection-1"
    }
  }
}
            ]]>
          </artwork>
        </figure>
      </t>
    </section>
    <section title="Backwards Compatibility">
      <t>
        The "links" value MUST be statically bound to the JSON "link" name.  If the semantics of the "links" object changes, then a new "link" name must be created.  When using the short abbreviations instead of a "rel" for the "link" name, when the semantics of the object is changed, eg a new version is available, a new short abbreviation must be created for the new href.  If changing any of the "rel", "link" name, or "href" media type, then the resource MUST define a new "link" name to use.
      </t>
      <t>
        The media type "application/links+json" MUST utilize only the canonical representation of a link.  This means that a link provided in the "links" SHOULD not be duplicated and provided under a different link relation for the purpose of changing the representation.  Each rel points to the semantic definition of the resource, while the resource can be duplicated in the "links" object, to vary the representation of a resource the "type" property of the "template" object should be utilized.  To provide canonical URL links to resource representations each representation MUST utilize a different link relation.  Because of the complexitiy associated with expectation on the "default" representation of a resource, to adhere to this RFC the "type" property SHOULD be used and summarily the "ACCEPT" header to request the appropriate representation, and the "links" object SHOULD NOT contain different representations of the same resource.  Since resources are linked to and not necessarily representations it often does not make sense to iterate the representation links, but instead provide a list of representations for a link.
      </t>
    </section>
    <section anchor="Acknowledgements" title="Acknowledgements">
    </section>
    <section anchor="IANA" title="IANA Considerations">
    </section>
    <section anchor="Security" title="Security Considerations">
    </section>
  </middle>
  <back>
    <references title="Normative References">
      &RFC2119;
      &RFC6838;
      &RFC7230;
      &RFC7231;
      &RFC8259;
      &RFC8288;
    </references>
  </back>
</rfc>