Encoding


The encoding layer defines the mapping between the document layer, and its byte string encoding.

Core API defines a canonical encoding scheme called Core JSON. Other encodings are also supported.


Core JSON

An implementation for Core JSON is built-in to the Python client library: core-api/python-client

Core JSON is a format that can be used to represent either Schema responses or Hypermedia response. It is designed to map cleanly to the Core API document model.

A document is represented using the JSON encoding. In addition to the standard set of JSON primitives, Core JSON adds the following:

The top level element in a Core JSON response MUST either be a Document or an Error.

The media type for this scheme is: application/vnd.coreapi+json.

An example Core JSON encoded document is demonstrated below.

{
    "_type": "document",
    "_meta": {
        "url": "/",
        "title": "Notes"
    },
    "notes": [
        {
            "_type": "document",
            "_meta": {
                "url": "/1de153fe-6747-41d3-bc0e-d9d7d87e448a",
                "title": "Note"
            },
            "complete": false,
            "description": "Email venue about conference dates",
            "delete": {
                "_type": "link",
                "action": "delete"
            },
            "edit": {
                "_type": "link",
                "action": "put",
                "fields": [
                    {
                        "name": "description"
                    }, {
                        "name": "complete"
                    }
                ]
            }
        }
    ],
    "add_note": {
        "_type": "link",
        "action": "post",
        "fields": [
            {
                "name": "description",
                "required": true
            }
        ]
    }
}

Document

The Document primitive is represented using an object which includes a key-value pair of "_type": "document".

The Link primitive is represented using an object which includes a key-value pair of "_type": "link".

Link parameters:

Error

The Error primitive is represented using an object which includes a key-value pair of "_type": "error".

Data primitives

The standard JSON primitives are represented as usual.

Handling unexpected types

Escaping reserved keys

The object keys "_type" and "_meta" are reserved, and should not be included in the standard parsing of key-value contents of Document or Object types.

Core JSON ensures that the reserved "_type" and "_meta" are still valid literal keys, by providing escaping and unescaping rules as detailed below.

Escaping reserved keys during encoding

When any object key matching the regular expression /[\_]+(type|meta)/ is encountered, it MUST be escaped by pre-pending an additional underscore character.

Unescaping reserved keys during decoding

When any object key matching the regular expression /_[\_]+(type|meta)/ is encountered, it MUST be unescaped by removing the leading underscore character.

Canonical style

The following canonical style indicates a set of guidelines that server implementations or client libraries MAY choose to follow, in order to generate a consistent output format for the JSON encoding.

Key ordering

Clients MAY choose to order any Object or Document keys in their output, as follows.

Omitting default values

Clients MAY choose to omit any values that are the default when encoding a document.

Clients MAY take advantage of the relative URL transformations made when parsing Documents and Links, in order to encode minimal URL outputs.

Indentation and spacing

Client MAY choose to use a concise style as the default. Using this style will ensure that no spacing or indentation is used between tokens.

Clients MAY choose to allow an optional verbose style. Using this style will ensure that ":" delimiters have a following whitespace, "," delimiters have no following whitespace, and elements are newline indented, with four space character indentation level.


HAL

Python implementation: core-api/python-hal-codec

HAL services MUST expose their endpoints with the application/hal+json media type.

Core API documents can be encoded in HAL, with a few limitations:

When interacting with a HAL service using Core API, you'll need to explicitly set any actions other than GET. For example, using the command line client:

coreapi action add_note -a post -p description="A new todo note"

Additionally, parameters will not be included in the link descriptions displayed by Core API documents.

Indexing by keys vs indexing by rel values.

HAL uses rel values to identify and index links and embedded documents, whereas Core API uses the key in the document.

In order to handle this Core API maps between HAL rel values and roughly equivalent key values. For example, if decoding a HAL document then the link's curie name will be as the key, if it exists.

Valid document structures.

HAL supports documents and links as top level items, where Core API supports documents and links nested anywhere in the parent document.

This introduces some limitations on the valid document structures that Core API can support in HAL representations.

Core API does not yet support help information being associated with links, which HAL provides for.


JSON Hyper-Schema

Python implementation: core-api/python-jsonhyperschema-codec

JSON Hyper-Schema endpoints MUST use the application/schema+json media type.

Core API can support decoding & interacting with JSON HyperaSchema endpoints.

The schema style is less expressive that true hypermedia, as it consists of a single monolithic entry point. Calls to the endpoint typically result in data being returned from the service, rather than a new hypermedia document. Nonetheless, using a Core API client library to interact with a service using its schema definition is far more robust and meaningful than constructing HTTP requests explicitly.

The additional benefit of schemas is that they can be created for existing APIs without any internal changes being required. Furthermore, if clients load the schema definition from disk, then no initial HTTP call to request the entrypoint is required.


OpenAPI / Swagger

Python implementation: core-api/python-openapi-codec

Core API can support decoding & interacting with OpenAPI / Swagger endpoints.

The following constraints currently exist, although future work is planned on each of these:


HTML

Python implementation: core-api/python-html-codec

Core API also allows servers to respond in a way that allows for direct Web browser based interaction with the API.

By providing an HTML encoding, a service may expose either an API that can be interacted with directly through the browser, or may expose HTML documentation pages, driven by the information in the Core API document model.

HTML Encoding

Above: An example of an API that can be interacted with in the browser.