JSON-ish
... thoughts on embedding HTML layout/presentation in JSON.
Something that has been bothering me a lot lately in hypermedia API formats is that JSON (and transitively JSON-LD) is purely data-oriented and it is awkward to intermingle layout.
JSON's processing model has two key aspects:
- declaration order doesn't matter
{"foo": 1, "bar": 2} == {"bar": 2, "foo": 1}
- you cannot use the same identifier
JSON.parse('{"foo": 1, "foo": 2}') == {"foo": 2}
And that's an issue because it means you can't easily declare layout/presentation like you would in HTML/XML. For example:
<!-- Declaration order matters. For example, this: -->
<form>
<div>hello world</div>
<input name='foo'>
<input name='bar'>
</form>
<!-- ... is different than this: -->
<form>
<input name='bar'>
<input name='foo'>
<div>hello world</div>
</form>As well as you can use the same identifier multiple times and it doesn't override:
<!-- Declaration order matters. For example, this: -->
<form>
<div>foo</div>
<div>bar</div>
</form>
<!-- ... is different than this: -->
<form>
<div>foo</div>
</form>The JSON-friendly way to make this work is to make your objects declare a tree. This is what it would look like:
{
@type: Form,
children: [{
@type: Div,
children: ["hello world"]
}, {
@type: Input,
name: "foo",
},{
@type: Input,
name: "bar",
}
]
}And this is awkward at best.
HTML, on the other hand, is great at representing layout/presentation, but it is bad at representing machine-readable data. For example, this is what intermingling UI and data looks like with microdata:
<!-- Here is an example of embedding data with presentation in HTML -->
<div itemscope itemtype='http://schema.org/WebSite'>
<!-- It is awkward to have to create these 'fake' UI elements
just to convey data -->
<a itemscope itemprop='url'>http://example.com</a>
<meta itemprop='name' content='My WebSite'>
<!-- It is super hard to represent nested structures because meta tags
aren't recursive -->
<meta itemprop='description' content='foo bar>
<form itemprop='potentialAction' itemscope
itemtype='http://schema.org/SearchAction'>
<input itemprop='query' name='q'>
</form>
</div>What follows is an exploration of what combining both worlds would look like: embedding HTML layout in JSON, optimizing for producers as opposed to consumers (i.e. starting from the assumption that you want to make this easy for "writers" being cool paying the cost for "readers").
HTML (-ish) layout controls in JSON (-ish).
These are @goto's personal notes from a variety of internal discussions at Google.
This is super draft-y, read at your own risk.
The basic idea was simple: bring all the goodness of the well stablished and well thought out hypermedia controls in HTML to JSON objects. Everybody is familiar with those and there is no need to re-invent the wheel.
Here [0, 1, 2, 3] is some background reading if you are interested in the motivations.
I'll go over the most basic hypermedia controls available in HTML and a mechanism to map them to JSON. At the end, I'll go over a couple of extensions to what HTML provides to address a few needs from APIs.
Processing Model
- This isn't really JSON (and transitively JSON-LD): declaration order matters. That's important because it is designed to declare layout/presentation and data, as opposed to just data + hypermedia controls. That's super unfortunate, but I think necessary.
- an object with a name that starts with @ starts new nodes, it is the equivalent of
<>tags in XML/HTML. e.g.@a == <a> - a primitive with a name that starts with @ is an attribute of the parent node, it is the equivalent of attributes in XML/HTML. e.g.
@a { @href: "foo" } == <a href="foo" > - custom properties (everything that isn't started with a @*) are added to the parent node's context.
- There is some sort of JSON-LD-like processing that converts all these things into a bound graph.
- // Comments are allowed.
The media type would be something like application/vnd.json-ish.
Affordances
We use a reserved token (@) to make the distinction between text and hypertext. Here are the main hypertext affordances:
Tag Control
@a Outbound links
@form Templated links
@link Inbound links
@meta Metadata
@A
The simplest (and possibly most powerful) hypermedia control is the ability to express outbound links.
{
kind: "issue",
id: "1234",
name: "this is an issue",
description: "things are not working!",
@a: { @href: "/issues", @rel: "home", @text: "All issues", @itemprop: "home" }
}
@Form
The second important hypermedia control for APIs is the ability to perform operations/actions. On the web, this is typically done via