mca blog

As interest in hypermedia-oriented implementations for the Web increases, I am getting more questions about a "proper" way to design and execute hypermedia designs. Along the way, I've developed a rather simple way to describe the contents of hypermedia messages and how to "think about message design" when creating an implementation for the Web.

It all boils down to three levels of information that all exist within the shared messages on the Web: Structure Semantics, Protocol Semantics, and Application Semantics. The good new is, all three of these are needed for any successful communication between client and server - no matter the implementation style. The bad news is, most of the time these levels are obscured or muddled at implementation time. For that reason many of us do not get the chance to think about them clearly. Hopefully this blog post will help in that department and spark some comment and additional thinking on the subject.

Structure Semantics

The first level is the Structure Semantics. This is the set of rules regarding how to create a well-formed message. XML has rather simple structure semantics. JSON's rules for well-formedness are a bit more vague but reachable since JSON.parse(...) turns out to be the ultimate arbiter of such things. Determining well-formedness of other, more complex media types (HTML, Atom, HAL, Collection+JSON) is tougher, but do-able even if external validators are not always available.

It turns out to be very difficult to build a successful Web implementation that does not contain structure semantics - and that's a good thing.

Protocol Semantics

The second level is the Protocol Semantics. This is the set of rules regarding how to fashion valid requests and responses using one or more message protocols. HTTP, FTP, WebSockets, etc. are all message protocols. Most implementations for the Web use human-readable documentation to describe these semantics. For example, typical RPC-style implementations document URIs, associated request rules (HTTP methods and headers), and any possible body content. Hypermedia-style implementations express the protocol semantics directly in the message (usually in the body, but sometimes in HTTP headers). The most common way this is done is to include rules for links and 'forms' that may appear in server responses (think HTML).

Registered media types don't often include hypermedia controls. For example, CSV, XML, and JSON have no definitions for hypermedia expression within the message. However some media types such as HTML, Atom, HAL, Collection+JSON (and others), do include the predefined ability to express protocol-level information within the message sent from the server.

Application Semantics

The third level is the Application Semantics. This is the set of rules that govern the way in which application-specific information is shared between client and server. This includes names of domain data elements (users, customers, products, etc.) and specific actions within the domain (adding a user, calculating tax on purchases, etc.). Well-formed requests and responses are ones that contain valid expressions of these domain-specific concepts. There are very few registered media-type designs that contain this level of specificity and the ones that do contain it are usually are aimed at an industry-wide domain (e.g. VoiceXML and Maze+XML).

There are some machine-readable examples of application semantics that can be used in conjunction with existing structurally semantic forms (XML, JSON, etc.). XSD, JSON-Schema and other schema-based document types do a good job of expressing application-specific information. There are other example such as WSDL for SOAP and it's cousin WADL.

Most of the application-level semantics exist as stand-alone content with no standardized way to apply that information to a message. Some media type designs are better than others at supporting application-level semantics. HTML, for example, as several attributes (id, name, class, rel) with which you can apply application-level semantic information to a message.

Design Hallmarks

When designing a message format, you will always need to solve for all three levels (structure, protocol, and application). The simplest approach is to select an existing structural format (XML, JSON, etc.) and then use human-readable documentation to apply the other two (protocol and application). Doing this puts an added implementation coordination between client and server, but is quite common.

Selecting (or designing) media types that include protocol semantics and/or support applying application semantics directly within the message puts added responsibility on the message designer(s) and standardizes much more of the way client and servers interact. This can increase the likelihood that compatible implementations can be done at a distance (both in space and time) and that implementors (client and server developers) have an opportunity to safely evolve communications over time including adding new interactions to the domain-space without the need for prior coordination with the initial message designer.. It is these two aspects of the Web (support for distance and evolvability) that are a hallmark of hypermedia-style designs.