Introduction

Statement Annotations provide a way to express knowledge about statements. Typical use cases for Statement Annotations include:

  • the temporal validity of information,
  • the origin of information, or
  • just a way to annotate a specific statement with a human readable comment.

Usage

If enabled on a specific type of statement or type of resource, you see a Statement Annotation flag beside every annotatable statement:

This flag has different statuses:

  • A white flag indicates, that there is no annotation on the statement, but the annotation feature is enabled for this statement.
  • A black flag indicates, that there is at least one annotation on the statement.
  • No flag indicates, that the annotation feature is NOT enabled on this type of statement.

Clicking on one of the flags opens the Statement Annotation dialog for this specific statement:

In the Statement Annotation dialog, you have the following options:

  • Review the current annotations on the statement.
    • For each Annotation Resource, you see a box with the header "Resource XXX Template YYY".
    • XXX is the Annotation Resource - you can click on it to jump to the Annotation Resource in Explore.
    • YYY is the Annotation Shape.
  • Edit the existing annotation (using the blue pen button).
    • Here you have all options of a normal shape-based editing form.
  • Add new annotations to the statement.
    • A drop-down list of available annotation templates (aka Node Shapes enabled to be used as Annotation Shapes).
    • Click Add to create a new annotation on this resource.
    • Here you have all options of a normal shape-based editing form.
  • Remove an annotation.
    • Click the red trash icon on the upper right corner of an annotation to remove this specific annotation.
  • Close the dialog, going back to the annotated statement resource.

Setup

In order to have a working Statement Annotation setup, the following steps need to be done:

Create a Statement Annotation Graph

Create a new Graph, edit its metadata and change the type to Statement Annotation Graph.

Setup and import the Statement Annotation Graph in your data graph

In your data graph, where the resources exist which you want to annotate, import the Statement Annotation Graph and select it as an Annotation Graph.

Create an Annotation Shape which will be used for Statement Annotations

In your Shape Catalog, select a Node Shape which you want to use for Statement Annotations, and set the option Provide as Statement Annotation Shape to true.

Allow Statement Annotations on specific Classes or Properties

Finally, you need to enable Statement Annotations on a specific Node Shape or Property Shape. Use the Enable Statement Annotations property for this.

This will enable the feature on the statements of all resources shown with this Node Shape or on all statements shown with this Property Shape.

Technical Background

From the technical point of view, the Statement Annotation feature uses RDF Reification to annotate Statements (Triples) with additional background information. Statement resources can be annotated with custom Annotation Resources. These Annotation Resources are based on specific Shapes which are enabled as Statement Annotation shapes. Reification Resources as well as Annotation Resources are managed in a Statement Annotation Graph, which need to be configured on a Graph as well as imported to this Graph. The following illustration depicts this schema with boxes and arrows:

Some notes on this:

  • There is one Statement Reification Resource per Statement Annotation.
  • Removing the Statement Annotation also removes the Statement Reification Resource.
  • All annotation triples (8 triples in the image) are created in the Statement Annotation Graph, so Step 2 of the setup procedure is important.

Querying Statement Annotations

In order to automate access to Statement Annotations, you can query them with SPARQL e.g. via cmemc or the API endpoint.

Here is a query example to start with:

# Request SPO of all Statement Annotations which annotate a triple of my ResourceIRI (parameter)

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT DISTINCT ?StatementAnnotationGraph ?AnnotationResource ?p ?o
WHERE {
  GRAPH ?StatementAnnotationGraph {
    ?StatementResource a rdf:Statement .
    ?StatementResource rdf:subject|rdf:predicate|rdf:object <{{ResourceIRI}}> .
    ?StatementResource rdf:value ?AnnotationResource .
    ?AnnotationResource ?p ?o
  }
}
CODE