Network Working Group                                           W. Parad
Internet-Draft
Intended status: Standards Track                             I. Sowinski
Expires: September 19, 2018
                                                          R. Nowosielski
                                                          March 18, 2018


                     JSON Hypermedia Links Notation
                       draft-wparad-json-links-00

Abstract

   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.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 19, 2018.

Copyright Notice

   Copyright (c) 2018 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of




Parad, et al.          Expires September 19, 2018               [Page 1]


Internet-Draft                 Links+JSON                     March 2018


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Link-Relation . . . . . . . . . . . . . . . . . . . . . .   3
     2.2.  Links . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.3.  JSON Link Property Name . . . . . . . . . . . . . . . . .   3
     2.4.  JSON Link Property Value Object . . . . . . . . . . . . .   3
   3.  Reserved Words  . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Links Notation Document . . . . . . . . . . . . . . . . . . .   4
   5.  Link Resources  . . . . . . . . . . . . . . . . . . . . . . .   4
     5.1.  rel . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     5.2.  href  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
     5.3.  templates . . . . . . . . . . . . . . . . . . . . . . . .   5
   6.  Discoverability . . . . . . . . . . . . . . . . . . . . . . .   5
   7.  Links Example . . . . . . . . . . . . . . . . . . . . . . . .   6
   8.  Backwards Compatibility . . . . . . . . . . . . . . . . . . .   7
   9.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   7
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   11. Security Considerations . . . . . . . . . . . . . . . . . . .   7
   12. References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     12.1.  Normative References . . . . . . . . . . . . . . . . . .   8
     12.2.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   This document introduces the media type "application/links+json" to
   support hypermedia linking inside JSON as defined by [RFC6838] and
   [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".

   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 web linking [RFC8288] by defining the
   semanitcs of a linked representation.





Parad, et al.          Expires September 19, 2018               [Page 2]


Internet-Draft                 Links+JSON                     March 2018


   The design of "application/links+json" proposes a straightforward
   model which combines the simplicity of JSON object with a predefined
   "links" structure.

   This document is being discussed in the draft-wparad-json-links
   Gitter room [1].

2.  Terminology

   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 [RFC2119].

   Following the JSON standard conventions defined in [RFC8259], the
   Links Notation will define specific definitions to each of the follow
   terms, as they are reused through the document.

2.1.  Link-Relation

   Also known as web linking [RFC8288], 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".

2.2.  Links

   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.

2.3.  JSON Link Property Name

   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.

2.4.  JSON Link Property Value Object

   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.






Parad, et al.          Expires September 19, 2018               [Page 3]


Internet-Draft                 Links+JSON                     March 2018


3.  Reserved Words

   The application/links+json reserves the following words which
   maintain their definition and no other value can replace them.  The
   are as follows:

      * "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.

4.  Links Notation Document

   A JSON Links Document uses the format described in [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".

   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.

5.  Link Resources

   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.

5.1.  rel

   The "rel" JSON name is OPTIONAL when the "link" property name is a
   link relation per [RFC8288], if not, then the "rel" property MUST be
   provided.  The "rel" MUST be either an "absolute-URI" or a predefined
   link relation.

   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



Parad, et al.          Expires September 19, 2018               [Page 4]


Internet-Draft                 Links+JSON                     March 2018


   representation multiple times and each it SHOULD specify a different
   "href".

5.2.  href

   The "href" JSON name MUST be provided and defines a the URL for a
   resource and MUST be an "absolute-URI" per [RFC7230].  When not
   defined the link relation is assumed from the "link" JSON object
   name.

5.3.  templates

   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 [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:

      * "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 Open API
      Schema [2] object.

6.  Discoverability

   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.

   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.






Parad, et al.          Expires September 19, 2018               [Page 5]


Internet-Draft                 Links+JSON                     March 2018


7.  Links Example

   Here is an example:


   {
     "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": {}
         }
       }
     }
   }


   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:



Parad, et al.          Expires September 19, 2018               [Page 6]


Internet-Draft                 Links+JSON                     March 2018


   {
     "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"
       }
     }
   }


8.  Backwards Compatibility

   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.

9.  Acknowledgements

10.  IANA Considerations

11.  Security Considerations







Parad, et al.          Expires September 19, 2018               [Page 7]


Internet-Draft                 Links+JSON                     March 2018


12.  References

12.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,
              <https://www.rfc-editor.org/info/rfc6838>.

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,
              <https://www.rfc-editor.org/info/rfc7230>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <https://www.rfc-editor.org/info/rfc7231>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [RFC8288]  Nottingham, M., "Web Linking", RFC 8288,
              DOI 10.17487/RFC8288, October 2017,
              <https://www.rfc-editor.org/info/rfc8288>.

12.2.  URIs

   [1] https://gitter.im/wparad/draft-wparad-json-links

   [2] https://github.com/OAI/OpenAPI-Specification

Authors' Addresses

   Warren Parad

   Email: rfc@warrenparad.net







Parad, et al.          Expires September 19, 2018               [Page 8]


Internet-Draft                 Links+JSON                     March 2018


   Igor Sowinski

   Email: igorsowinski.mail@gmail.com


   Rafal Nowosielski

   Email: rafal@nowosielski.email











































Parad, et al.          Expires September 19, 2018               [Page 9]