Internet DRAFT - draft-wparad-json-links
draft-wparad-json-links
Network Working Group W. Parad
Internet-Draft
Intended status: Standards Track I. Sowinski
Expires: March 5, 2019
R. Nowosielski
September 1, 2018
JSON Hypermedia Links Notation
draft-wparad-json-links-03
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 March 5, 2019.
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 March 5, 2019 [Page 1]
Internet-Draft Links+JSON September 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 . . . . . . . . . . . . . . . . . . . . . . 8
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
11. Security Considerations . . . . . . . . . . . . . . . . . . . 8
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
12.1. Normative References . . . . . . . . . . . . . . . . . . 8
12.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
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 March 5, 2019 [Page 2]
Internet-Draft Links+JSON September 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 March 5, 2019 [Page 3]
Internet-Draft Links+JSON September 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 March 5, 2019 [Page 4]
Internet-Draft Links+JSON September 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 March 5, 2019 [Page 5]
Internet-Draft Links+JSON September 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 March 5, 2019 [Page 6]
Internet-Draft Links+JSON September 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.
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
Parad, et al. Expires March 5, 2019 [Page 7]
Internet-Draft Links+JSON September 2018
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.
9. Acknowledgements
10. IANA Considerations
11. Security Considerations
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>.
Parad, et al. Expires March 5, 2019 [Page 8]
Internet-Draft Links+JSON September 2018
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
Igor Sowinski
Email: igorsowinski.mail@gmail.com
Rafal Nowosielski
Email: rafal@nowosielski.email
Parad, et al. Expires March 5, 2019 [Page 9]
