The PRAG-JSON Media Type (Pragmatic Representation of Application Grammars)

PRAG-JSON was designed to mimic the low-barrier of entry and high usability found in HTML ([HTML5]). Hypermedia-aware formats like HTML are one of the key reasons the Web become so widespread so quickly. It tapped into the ability to link documents together quickly and easily without much ceremony or engineering skills. It is hoped that PRAG-JSON will show how easy it is to create and use an application-level computer messaging format that supports a high degree of loose coupling and extreme late binding ([KAY2003]).

PRAG-JSON was designed to compliment the book "Design and Build Great Web APIs' ([DABGWA]). This book is a collection of lessons and common practices aimed to help the reader through the process of creating hypermedia-style APIs quickly and easily.

Another key motivator for the design of PRAG-JSON is to create web-based hypermedia format that works well in machine-to-machine (M2M) interactions. The foramt is simple in structure (metadata, links, items) and all the key elements support the use of unique in-document identifiers (id). These structure elements make is easy to associate data and actions from semantic profiles with exact elements within the response representation — an important key to successful M2M processing of content w/o relying on inference or other AI/ML support.

There is an open source repository [REPO] for this specification. Readers are encouraged to submit updates via the repository any time.

An implementation (client or server) of this specification is not compliant if it fails to satisfy one or more of the MUST or REQUIRED elements. An implementation that satisfies all the MUST and REQUIRED elements as well as all the SHOULD and RECOMMENDED elements is said to be "unconditionally compliant"; one that satisfies all the MUST and REQUIRED elements but not all the SHOULD and RECOMMENDED elements is said to be "conditionally compliant."

Below is a sample PRAG-JSON document example:

The media type identifier string for PRAG-JSON documents is: application/vnd.prag+json This SHOULD be used as part of the HTTP accept header when making a request for a PRAG-JSON document. It SHOULD appear as the HTTP content-type header when sending a response that contains a PRAG-JSON document.

The metadata element is meant to hold message-level information about the payload of the response. This might be individual data properties that describe the payload, references to other related content, etc. Anything that might be needed in order to improve the understanding of the payload itself. The role played by the metadata element in PRAG-JSON is similar to the role played by the meta tag in HTML5 ([HTML5-TAG]).

The metadata element is an array of anonymous JSON objects. The default properties of metadata objects that SHOULD appear are name and value. Possible additional properties that MAY be part of a metadata object include: id, type, title, tags, href and others. Other properties not defined by this specification MAY appear as well.

The metadata element SHOULD NOT contain any link or item elements as they are meant to appear in their own collection.

The links element contains any links and/or forms associated with the PRAG-JSON document. The links collection is an array of anonymous JSON link objects. These link objects are designed to carry complete details on Web navigation between resources including any protocol methods, arguments, and so forth. Any time the message needs to render a navigation or state change, this should appear as a link object. The links object plays a role in PRAG-JSON similar to HTML5’s link (HTML5-LINK), a (HTML5-A), and form (HTML5-FORM) tags.

The default properties of a link object that SHOULD appear are: name, href, method, and properties. Additional properties that MAY appear are: id, title, rel, tags, type, and enctype. Other properties not defined by this specification MAY appear as well.

The properties array within a link object contains one or more anonymous property objects. A property object SHOULD have name and value properties. It MAY have additional properties including id, title, required, readonly, pattern, type, and tags. Other properties not defined by this specification MAY appear as well. The role the property object plays in PRAG-JSON is similar HTML5’s input (HTML5-INPUT) element.

The links element SHOULD NOT contain any metadata or +item elements as they are meant to appear in their own collection.

The item element contains one or more data items that represent the state of the requested resource. The items collection is an array of anonymous JSON arbitrary objects. The items collection SHOULD contain a homogeneous JSON objects (e.g. all customer objects) but MAY contain a heterogeneous collection of objects.

Each item object SHOULD have id, type, and schema properties and MAY have any number of additional properties. The data for an item MAY be a set of properties at the "top" level or MAY be nested within a single named code (e.g. graph or data, etc. Each item object is essentially a graph arbitrary depth and complexity. The schema property of an item SHOULD provide enough information to allow message-handlers to properly parse the item.

The schema property SHOULD point to a JSON-Schema (JSON-SCHEMA) document but MAY point to some other document.

An item object MAY also include a single links collection. This links collection within an item object follows the same rules as the top-level links collection (see above).

Below is a list of valid PRAG-JSON properties defined in this specification. These properties MAY appear in more than one place within a valid PRAG-JSON message.