The Object-RDF-Mapping library Anno4j recently released a new version 2.3, which was done as a result to the newest draft of the Web Annotation Data Model WADM in July 2016 by the Web Annotation Working Group. The newest WADM draft introduced new additions and some changes to the existing model. The library adapted to that state. Discussed here are the major changes done to the library.

A New Set of Classes

All classes supported by the WADM are now implemented and available by default via Anno4j. Some of them had been omitted so far, others are new additions in the latest edition of the model. The added and/or adjusted classes are:

  • Intended Audience: The Audience indicates the group of people an Annotation was created for. This can for example be a specific type of occupational group, like teacher and student, or the definition of a human feature, like age and gender.
  • Choice for Bodies and Targets: Instead of supporting multiple bodies and/or targets directly, a Choice can be defined in between, which semantically indicates that only on choice of the respective body or target should be applied and interpreted of the given Annotation.
  • State of Annotations: A State of an Annotation represents the state that an Annotation is in. That state should also be applied at request/representation point. Annotations might change over time, or have a certain format that should be used. Available states are the TimeState and RequestHeaderState. States can also be refined by using the relationship oa:refinedBy.
  • Styling: CSS styling can be supported for Annotations in order to deliver rendering information next to the actual content.

A new feature with corresponding RDF classes are the Collections of Annotations. Collections are utilised when multiple Annotations are to be retrieved by a client. Two major classes with respective relationships and properties have been added:

  • Annotation Collection: A Collection contains multiple Annotation Pages, has provenance information, and might support descriptive discovery information about itself.
  • Annotation Page: Annotation Pages are part of an Annotation Collection and contain actual Annotations, pointers to the Collection as well as previous and following pages, and a start index.

New Selectors have been added to the previously available set. The new ones are:

  • CSS Selector: This Selector allows the selection of content in HTML Document Object Models.
  • XPath Selector: Similar to the CSS Selector, this selector is also used to select content out of a Document Object Model, but rather than using CSS selectors, this one accepts XPath expressions.
  • Range Selector: Range Selectors are used in order to combine two various other selectors. The content that is then selected begins with the start of the first selection and ends with the start of the second selection (not including it).
  • Refinement of Selections: Sometimes, using a single Selector is not enough, or not precise enough. By attaching another Selector via the oa:refinedBy relationship, the Selection of one Selector is applied to the content selected by the other.

Addition and Alteration of Relationships and Properties

Next to new classes introduced by the newest WADM version, new relationships and properties have also been added to Anno4j:

  • Format and Language: For Body and Target nodes, a (or optionally multiple) dc:format and/or dc:language properties can be supported in order to indicate the format and language of the respective resource.
  • Modification of Resources: The property dcterms:modified with a value of a timestamp (conform to the W3C Datetime Format) is used to indicate the point of time at which a given resource has been modified last.
  • Rights Information: The dcterms:rights relationship supported at Annotation level is used in order to link to a license or rights statement. This illustrates the conditions under which the Annotation may be used.
  • Other Identities: Two relationships, attached at Annotation, Target, or Body nodes, are used to convey provenance information. A oa:canonical relationship points to the original IRI of a given resource, while the oa:via relationship links to an IRI that a resource was obtained from by the system.
  • Rendering Software: Links to a piece of software or system that was used to render the given Specific Resource/Target when the associated Annotation was created.

Some properties and relationships that were used for provenance information got reworked and renamed (see here), formerly known as oa:serializedAt, oa:serializedBy, oa:annotatedAt, and oa:annotatedBy:

  • Resource Creation: An Agent, attached to the resource (Annotation, Body, or Target) via the dcterms:creator relationship, creates the resource at a given timestamp, which is attached via the property dcterms:created.
  • Annotation Generation: An Agent, attached to the Annotation node via the as:generator relationship, generates the serialisation of an Annotation at a given timestamp, which is attached to the Annotation node via the property dcterms:issued.

In the previous version of Anno4j, not all multiplicities and cardinalities were implemented correctly. Now, all of them are implemented accordingly.

Minor Implementation Details

The Anno4j library is built upon the OpenRDF library Alibaba, and can therefore benefit from its API as well as Java advantages.

  • Hierarchy Implementation in Anno4j: Implementing hierarchical interfaces keeps the Java code short and precise, while still supporting the whole required RDF functionality.
  • Correct Value Checks: Using Java, before setting (and especially persisting) given values at a property, a check can be fulfilled in order to determine if its format is correct. For example, a W3C Datetime timestamp can be checked for its integrity. For some properties, helper functions that automatically create a correct value are supported.
  • Ontology Adaptation: Anno4j comes with a predefined set of RDF vocabulary that is used by the WADM. All of those classes and instances have been adjusted to the new draft.