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 →