Open Annotation context

The context defines the meaning of the terms used in a JSON-LD document.

This page touches briefly on how context is used in JSON-LD, and then presents the specific context used in RESTful Open Annotation documents. If you are already familiar with JSON-LD, you may want to jump straight to the context definition.

Introduction

JSON documents use names such as parent, which are short but ambiguous: for example, “parent” can refer to the mother or father of a person, or the containing data item in a hierarchical model.

By contrast, Linked Data uses URIs such as http://purl.org/vocab/relationship/parentOf and http://sioc-project.org/ontology#term_has_parent for names. These are unambiguous, but too verbose for normal human use.

Here’s where the context comes in. It allows us to define that when we write parent, we mean http://purl.org/vocab/relationship/parentOf. The context allows us to avoid ambiguity when writing JSON-LD such as

{
  "parent": "Eve",
  ...
}

In a bit more technical detail, JSON-LD defines algorithms that expand JSON documents such as the above with respect to a given context to produce documents such as

{
  "http://purl.org/vocab/relationship/parentOf": "http://example.org/people/Eve",
  ...
}

and compact expanded documents to recover the short forms.

So, in JSON-LD the keys (such as parent above) expand into full, globally unique URLs. It is also good practice to provide useful information on look-up, so that e.g. http://purl.org/vocab/relationship/parentOf gives the definition of “parent” relevant to the current context.

Core OA context

RESTful OA uses a context based on a version of the recommended Open Annotation context. The full context defines names for talking about motivations for annotating, styling for display, and source document caching, among other things.

While these are all important issues, we can get started with much less. Below is a minimal “core” of the context.

"@context": {
  "oa" :       "http://www.w3.org/ns/oa#",
  "body" :     { "@id": "oa:hasBody" },
  "target" :   { "@id": "oa:hasTarget", "@type": "@id" }
}

The first line defines oa to be a prefix corresponding to http://www.w3.org/ns/oa#.

The second line then defines body to be a term that maps to the compact form oa:hasBody. Using the definition of the first line, this form can be expanded to the full URL http://www.w3.org/ns/oa#hasBody.

The third line defines a similar expansion for target, adding also "@type": "@id". This somewhat opaque piece of syntax simply means that the values of target are URLs. (This is how JSON-LD adds hyperlinks to standard JSON, which lacks them.)

(See data model for definitions of target and body.)

Full context definition

The full context definition for the RESTful Open Annotation API is available from http://178.79.168.194/ns/restoa.jsonld. It is recommended that systems using the API use this context, for example by referencing it as follows:

{
  "@context": "http://178.79.168.194/ns/restoa.jsonld",
  ...
}

The bulk of this context is simply the latest version (Dec. 2014) derived from the Open Annotation context by the W3C Web Annotation WG, which is carrying on the OA standardization effort.

The OA context is presented in great detail in Open Annotation and Web Annotation WG materials, so we won’t give a detailed explanation here.

Instead, we simply present the modest extensions that the RESTful Open Annotation API makes to the W3C working draft context.

In brief, to implement the collection pattern frequently seen in RESTful APIs, we define a prefix for standard link relations

"lrel" :  "http://www.iana.org/assignments/link-relations/#"

And define terms matching the standard use of a few link relations, as follows:

"prev":          {"@type":"@id", "@id" : "lrel:prev"},
"next":          {"@type":"@id", "@id" : "lrel:next"},
"last":          {"@type":"@id", "@id" : "lrel:last"},
"item":          {"@type":"@id", "@id" : "lrel:item"},
"collection":    {"@type":"@id", "@id" : "lrel:collection"},

Servers implementing pagination (see extensions) must use these terms to identify the URLs for the next, last, etc. pages of the collection.

Extending the context

Applications may prefer to use also terms and prefixes not defined in the default context, for example using Person or schema:Person for http://schema.org/Person.

Rather than creating alternate versions of the recommended context, we strongly recommend that implementations use “mixin” contexts with the following pattern:

{
  "@context": [
    "http://178.79.168.194/ns/restoa.jsonld",
    "http://example.org/my-context.jsonld"
  ],
  ...
}

Multiple contexts are a standard part of JSON-LD. Possible conflicts such as multiple definitions of a single term are resolved using the most-recent-definition-wins rule.