The document layer is the set of primitives that a Core API client interacts with.

The available primitives include both data and actions, and may be composed in nested structures.

Clients interact with a Core API service solely through interacting with the document layer. In doing so they do not require any information about the underlying transport or encodings used.

The specification for mapping documents onto byte strings is documented by the encoding layer. The specification for how network requests are made is documented by the transport layer.

The document primitives

The top level element in a Core API interface MUST be a Document or Error.


A document is used as a container for the data and actions provided by the interface.

A link is used to represent a possible transition that the client may take.

Links parameters allow a client to include additional information as part of a transition, and may affect the resulting URL, query parameters or request body.

Data primitives

Data primitives are the set of basic datatypes that may be used to represent data in the interface.


Errors are exception states that may occur when a transition fails. This element allows the server to respond with a message or messages indicating why the transition could not be effected.

Errors are similar to Documents, but because they do not represent a successful transition they are not associated with a URL.

Interacting with documents

Documents provide both the data and available actions to the client, allowing clients to both inspect the available data, and to interact with the service.

A link transition is effected as follows:

When a link is followed, an appropriate transport should be selected based on the scheme of the URL.

The transport is then responsible for returning either a new Document, or an Error condition.