Alph Link Documents

Alph's link documents are just named JSON-LD graphs. The standard template for one of these will look like the following:

{
  "@context" : [
    "https://schema.org",
    {"@vocab" : "http://alph.io/terms/",
      "@base" : "#" }
  ],
  "@id" : _document_IRI_ ,
  "@type" : "AlphLinkDocument",
  "@graph":[

    /* ...links... */

  ]
}

That's it. A container for a graph.

Of course, additional properties may be added to give the document an author, name, description, and so-on. The schema.org vocabulary provides definitions for these terms, as well as a whole host of others.

Within the "@graph" attribute, the basic structure of a link is this:

{
  "@id": _A_node_ ,
  _relation_ : _B_node_
}

_A_node_ is going to be an IRI. For Web linking, that's usually going to be an HTTP(S) URL. _B_node_ can also be a URL, but it might also be one of a few different types of object node unique to Alph. We'll get into those in a moment.

So, to represent a simple link between two Web documents, you'd have something that looked like:

{
  "@id" : "http://foo.site/review",
  "about" : "http://bar.site/book"
}

If you were linking one fragment of a plain text to a fragment of another, the link could look like the following.

{
  "@id" : "http://foo.site/essay1#123-456",
  "related" : "http://bar.site/essay2#789-1011"
}

The fragments here are given in terms of Alph's Simple Selectors. At the time this document is being written I only have plans to support Simple Selectors, bare name pointers (ex.: http://host/path/resource#fragment_id) , and Alph's implementation of the element() and range() XPointers in both alph.js and alph.py .

Multiple links of different relations coming from the resource named by the @id attribute can be expressed easily, and multiple links of the same relation can be given in an array:

{
  "@id":"http://foo.site/Dad",
  "marriedTo": "http://foo.site/Mom",
  "siblingOf": "http://foo.site/Uncle",
  "hasChild": [
      "http://bar.site/Beauford",
      "http://bas.site/Chachi"
  ]
}

People familiar with JSON-LD know how this works already, so I don't need to go into it here.

The EDL Type

One complication when dealing with linking for xanalogical documents is this: we must be able to link between *concatenations of media fragments*. This is essential because a sentence or a paragraph that appears in a xanalogical document may not be a contiguous portion of a single source text. It may, in fact, be a concatenation of fragments from multiple source texts. So, we need to be able to link between these metafragments, and the way we do this is by creating nodes of the "EDL" type.

{
  "@id" : "_:1",
  "@type" : "EDL",
  "@list" : [
        "http://some.site/text1#123-456",
        "http://some.site/text1#789-1011",
        "http://other.site/text2#123-456"
  ],
  "related" : {
    "@id" : "_:2" ,
    "@type" : "EDL",
    "@list" : [
          "http://third.site/text3#111-222",
          "http://third.site/text4#333-444"
    ]
  }
} 

EDL objects are typically going to be blank nodes and have document-local @id attributes.

Note that the @list attribute is an RDF List, an ordered collection.