| Network Working Group | W. Parad |
| Internet-Draft | |
| Intended status: Informational | I. Sowinski |
| Expires: September 24, 2018 | |
| R. Nowosielski | |
| March 23, 2018 |
JSON Hypermedia Links Notation
draft-wparad-json-links-01
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.
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 24, 2018.
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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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 by defining the semanitcs of a linked representation.
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.
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.
Also known as web linking, 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".
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.
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.
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.
The application/links+json reserves the following words which maintain their definition and no other value can replace them. The are as follows:
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.
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.
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 representation multiple times and each it SHOULD specify a different "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.
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:
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.
{
"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": {}
}
}
}
}
Here is an example:
{
"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"
}
}
}
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:
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.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC6838] | Freed, N., Klensin, J. and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013. |
| [RFC7230] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014. |
| [RFC7231] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014. |
| [RFC8259] | Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017. |
| [RFC8288] | Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017. |