JSON Hypermedia Links Notation

This document introduces the media type "application/links+json" to support hypermedia linking inside JSON as defined by and . 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 . Following the JSON standard conventions defined in , 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: * "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.

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

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.

Here is an example:

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.