DocJSON – JSON HyperMedia Documents


A DocJSON document consists of standard JSON with the addition of a set of hypermedia controls that are used to express the actions that may be taken. DocJSON is a flexible document format that does not impose any structural restrictions either on the data representation style or on the layout of hypermedia controls used within the document.

The true power of the spec lies in restrictions it oposes:

A document may be any valid JSON with the single restriction that the object key "_type" is reserved.

Real genius imho, as it allows the implementer to use any specific structure he wants instead of imposing a structure as other formats such as Collection+JSON, Siren, Hal, JSON-LD, etc. do.

If for one always inject the returned HTTP status code as a status object into the response (example). With DocJSON I’m allowed to do so, plus I can make my API discoverable by consumers who have no prior knowledge of the keys it holds.

Linking back to some HyperMedia things I’ve been tinkering about myself this might actually formulate the answer to the problem I had: wanting to roll my own structure without needing to register a new format (which one shouldn’t).

Looking forward to how this spec will evolve 🙂


Related: JSON API →

Published by Bramus!

Bramus is a frontend web developer from Belgium, working as a Chrome Developer Relations Engineer at Google. From the moment he discovered view-source at the age of 14 (way back in 1997), he fell in love with the web and has been tinkering with it ever since (more …)

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.