How do we encode textual information in the Hypermedia protocol?

Text Encoding Techniques

Generally there are two ways to form text annotations. Take the following example where we write "Hello world":

Inline Structure

This is how HTML works. Using the paragraph (<p>) and bold (<b>) tags, it would look like:

<p>
  Hello <b>world</b>
</p>

Standoff Properties

This approach allows the text to stand apart from the annotations, which are "standoff" as they are saved independently.

{
  "text": "Hello world"
  "annotations": [
    { "type": "bold", "at": [6, 11] }
  ]
}

This is (roughly) the approach that we use in the Hypermedia protocol.

Benefit of Standoff Properties

At first glance, the HTML approach seems more readable. But as more annotations appear, which may overlap, the complexity becomes more apparent.

Consider the example text of "overlapping annotations cause problems"

With HTML, this must be encoded as:

<p>
  <em>overlapping <b>annotations</b></em> <b>cause problems</b>
</p>

Notice how there are two bold tags even though there is only one range of bold text.

With Standoff Properties we have a much cleaner result:

{
  "text": "overlapping annotations cause problems"
  "annotations": [
    { "type": "italic", "at": [0, 23] }
    { "type": "bold", "at": [12, 38] }
  ]
}

This becomes even more important as we support a more diverse set of text annotations over time, and support annotations from a variety of authors.

Linking

As we support linking and back-linking, we have situations where people may choose similar but different ranges of text.

In HTML, it is impossible to have overlapping links where one range text is annotated with multiple links, because HTML disallows nesting of <a> anchor tags.

<p><a href="foo">Foo <a href="bar">bar</a></a></p>

In Hypermedia text blocks we can theoretically support this quite easily (although we don't, yet!):

{
  "text": "foo bar"
  "annotations": [
    { "type": "link", "at": [0, 7], "to": "foo" }
    { "type": "link", "at": [4, 7], "to": "bar" }
  ]
}

In the future we plan to support this, as well as showing backlinks to overlapping ranges of text.

References

The term was coined by Desmond Schmidt in his 2016 paper

standoff-properties.pdf