The MASH-JSON Media Type (Machine Acessible Semantic Hypermedia)

MASH-JSON is designed to make it easy for "headless" machines to interact with each other on the web using common patterns from the web. The format makes both data and actions explicit within the response representation and has design elements (id, name, & rel) that can hold unique identify information that does NOT rely on the resource’s location (URL) or it’s semantic contents (givenName, familyName, etc.).

MASH-JSON taps into the power of the web by making it easy to link resources, easy to discover and follow those links, and easy to predict what will be at the "other end" of the link before it is followed. MASH-JSON was designed with HTML ([HTML5]) in mind but should be helpful in other network-level protocols that follow a similar pattern (identifier, headers, & body).

MASH-JSON supports a high degree of loose coupling by limiting protocol knowlege to supporting links for forms and limiting domain data knowledge to supporting an application profile identifier (e.g. via Application-Level Profile Semantics ([ALPS]).

MASH-JSON was designed to compliment the book RESTful Web Microservices ([RWMBook]). This book is a collection of recipes and principles to help readers through the process of creating microservice-style implementations that rely on hypermedia to connect and share information at runtime.

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 MASH-JSON document example:

The media type identifier string for MASH-JSON documents is: application/vnd.mash+json This SHOULD be used as part of the HTTP accept header when making a request for a MASH-JSON document. It SHOULD appear as the HTTP content-type header when sending a response that contains a MASH-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 MASH-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 forms or items elements as they are meant to appear in their own collection.

The forms element contains any links and/or forms associated with the MASH-JSON document. The forms collection is an array of anonymous JSON form objects. These form 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 form object. The forms object plays a role in MASH-JSON similar to HTML5’s link (HTML5-LINK), a (HTML5-A), and form (HTML5-FORM) tags.

The default properties of a form object that SHOULD appear are: id", +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 form 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 MASH-JSON is similar HTML5’s input (HTML5-INPUT) element.

The forms element SHOULD NOT contain any metadata or +items 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 forms collection. This forms collection within an item object follows the same rules as the top-level forms collection (see above).

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