Fork me on GitHub

JSON/Hypcos – JSON Hypermedia Controls



JSON is a popular media type used for building web APIs. While good as a data format, JSON is not a hypermedia type as it lacks means of application flow control (hypermedia controls). Although attempts were made to build a JSON-based hypermedia type (most notably Hypertext Applicataion Language – HAL), still JSON implementations aren't on par with more mature XML-based hypermedia types.

JSON hypermedia controls (Hypcos) are not intended to become the missing all-in-one JSON hypermedia type but rather to provide standard building blocks for constructing new and extending existing hypermedia types. JSON hypcos intentionally duplicate (actually combine) some of the existing efforts, overlap or even conflict with each other. API designers are encouraged to cherry-pick and mix JSON hypcos together to define a media type.

Hypermedia Factor

Mike Amundsen defined a classification of media types based on the level of hypermedia support. H-Factor identifies 9 values which can either be supported by a media type or not:

  1. LE: Embedding links
  2. LO: Outbound links
  3. LT: Templated queries
  4. LN: Non-Idempotent updates
  5. LI: Idempotent updates
  6. CR: Control data for read requests
  7. CU: Control data for update requests
  8. CM: Control data for interface methods
  9. CL: Control data for links

Hypcos cover all the listed H-Factor values being a valuable foundation for a full-fledged hypermedia type.

Hypermedia Controls

Link Value

The simplest possible way to describe a linked resource is to represent its URI as a value of a JSON attribute:

"venue": ""

The name of the attribute conveys the relation type (CL factor) while the URL value represents LO.

Link Object

A link object is a more sophisticated representation of a link concept in JSON. Derived from HAL links, link objects provide extensibility to links:

  "href": ""

In its simplest form the link object only represents the LO factor, but its power is in combination with other hypcos.

Link Relation

This is a HAL flavor to represent a relation type (CL) of a link object:

"venue": { "href": "" }

Link Relation Attribute

Another flavor is to represent the relation type (CL) as an attribute of a link object:

  "rel": "venue",
  "href": ""

Self Link

A link with the self relation type contain the canonical resource URI and identifies a resource in a JSON soup. Self link relation type can be represented with both Link Relation and Link Relation Attribute hypcos.

Links Hash

A hash (or map) of links can be used to group outbound links of a resource together and thus improve discoverability of links for clients. Links can be represented by either Link Value or Link Object and are stored in a hash by their relation types:

"links": {
  "venue": <link>,
  "organizer": <link>

HAL always imply Link Object representations and use "_links" attribute instead of "links". Underscore is a taste preference. HAL uses underscores to avoid name clashes, but what other semantic can the word 'links' have in the context of a hypermedia resource?

Links Array

Another option to group multiple links together is to put them in an array. Links Array can be used in conjunction with Link Relation:

"venues": [<link1>, <link2>, ...]

Links Array can also be used with Link Relation Attribute:

"links": [
    "rel": "venue",
    "href": ""
  }, {
    "rel": "organizer",
    "href": ""

Templated URI

The server can instruct clients to construct resource URIs by expansion of URI Templates with parameters:


Templated URI Attribute

To distinct templated URIs, they can be put in a special href-template attribute:

"href-template": "{?input,offset,count}"


Pre-constructed and pre-filled JSON object that the client can alter before sending back to the server. The client alters only the parts it understands, thus template is a way to get hidden fields of HTML forms in JSON. When used in a Link Hypco can provide LN H-Factor.


Embed JSON Schema snippets to describe semantics of data.


Hypermedia controls defined in this document are standard building blocks which can be reused individually or all at once. Since Hypcos are defined as JSON objects with only optional attributes every JSON media type can be gradually enriched by JSON hypcos to provide required level of application flow control.


As an example of building a media type out of JSON hypcos let's consider HAL, which can be described as:

HAL is a superset of Link Object + Link Relation + Self Link + Links Hash + Links Array + Templated URI

However HAL uses "_links" for the links hash name though the description is not strict. In HAL resources can also embed other resources in the "_embedded" hash. Resource embedding may become a separate JSON hypco in future. For now I consider it to be just Self Link+Link Relation+Link Object+Links Hash – whenever a hypco-aware client encounters an object with a self link object in a links hash, it should consider it to be an embedded resource of its own right.


  1. Hypertext Application Language
  2. H Factor
  3. URI Templates
  4. JSON Schema