Funded by the Andrew W. Mellon Foundation
This project is maintained by Brown-University-Library
The Open Annotation plugin for Fedora is a content-agnostic web service that allows developers to create, query, retrieve, and serialize annotations using the Fedora Commons repository software to store annotations and their content. The plugin is designed to implement the Open Annotation Core Data Model:
The Open Annotation Core Data Model specifies an interoperable framework for creating associations between related resources, annotations, using a methodology which conforms to the Architecture of the World Wide Web. Open Annotations can easily be shared between platforms, with sufficient richness of expression to satisfy complex requirements while remaining simple enough to also allow for the most common use cases, such as attaching a piece of text to a single web resource.
An Annotation is considered to be a set of connected resources, including a body and target, and conveys that the body is somehow about the target. The full model supports additional functionality, enabling semantic tagging, embedding content, selecting segments of resources, choosing the appropriate representation of a resource and providing styling hints for consuming clients.
Note: A full installation is recommended for a production system
webapps/oac_web_service/fedora_settings.py file and enter the following information:
FEDORA_HOST : the host of your fedora installation, as accessed by the java servlet container ie. http://localhostFEDORA_PORT : the port of your fedora installation, ie. 8080FEDORA_USER : the fedora username to connect as. this user must have access to the API-M methods of the REST API
FEDORA_PASS : the password for the above userOAC_USER : the username you would like to use to authenticate with the OA servicesOAC_PASS : the password you would like to use to authenticate with the OA serviceswebapps/oac_web_service/fedora_settings.py file to somewhere outside of your Java Servlet's directory tree.
The user that runs your Java Servlet container will need read permissions on this new file
FEDORA_SETTINGS to point to the new fedora_settings.py file you just created. For example, if using Tomcat on Linux, create or edit the $CATALINA_HOME/bin/setenv.sh file and add the following line:
export FEDORA_SETTINGS=/the/location/of/your/new/fedora_settings.pyfedora_settings.py file and enter the following information:
FEDORA_HOST : the host of your fedora installation, as accessed by the java servlet container ie. http://localhostFEDORA_PORT : the port of your fedora installation, ie. 8080FEDORA_USER : the fedora username to connect as. this user must have access to the API-M methods of the REST API
FEDORA_PASS : the password for the above userOAC_USER : the username you would like to use to authenticate with the OA servicesOAC_PASS : the password you would like to use to authenticate with the OA servicesTo keep the Open Annotations index to stay in sync with Fedora, only one of the following two options needs to be done.
1.) Messaging
Messaging will ensure that the Open Annotation index is always in sync with Fedora, but requires that your Fedora instance is sending update messages to a JMS broker.
webapps/oac_web_service/WEB-INF/web.xml file and uncomment the <listener> tag at the bottom so it looks like:
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
webapps/oac_web_service/WEB-INF/spring/jms.xml file and change the following:
brokerURL in <amq:connectionFactory id="amq.connectionFactory" brokerURL=""/>destination in <jms:listener destination="" ref="consumer.messageListener" />destination is the topic that the OAC service will listen to. This defaults to Fedora's default: fedora.apim.update.
2.) Web Service
There are two service endpoint available for syncing the internal triple store with Fedora.
There are four main services the Open Annotation plugin provides:
A POST method that creates an Annotation (A-1) object
based on a number of parameters.
Required Parameters:
source_uri: The URI for the whole target object
dc_title: Dublin Core title associated with the annotation,
i.e. "dublin core title goes here"
body_inline Plain text string to store as the body
OR
body_uri: URI pointing to the body of the annotation
OR
body_content: Contents of the body (XML, text, json, etc.)
AND
body_mimetype: Mimetype of the body_content
Optional Parameters:
annotator: A string representing a user ID (0 or more)
ie. 'Charly'
generator: A string representing what generated the annotation
ie. 'Web Client'
oax_style_uri: A URI for a XSLT stylesheet used to render the whole target object. (0 or 1)
oa_selector: A string with the selector value(0 or 1)
oa_selector_type_uri: Required if an oa_selector is passed in
ie. oa:Fragment
fragment_type: URI describing the oa_selector type Optional and only used if
an oa_selector is passed in.
ie. 'http://www.w3.org/TR/xpath/'
body_content_model: A string representing the body's content model
ie. 'tei-annotation'
A GET method that takes a comma seperated list of Annotation
(A-1) PIDs to serialize as the 'pid' parameter.
Required parameters:
pid: Comma seperated list of PIDs to serialize.
Optional parameters:
format: Format of the serialization output
Options:
- rdf/xml or xml (default)
- rdf/json or json
- turtle or ttl
- nt
- n3
A POST or GET method to query the Open Annotations index with a SPARQL Query
This method has READ access to the Annotations index.
Required parameters:
query: The SPARQL query to execute
Python examples:
A GET method that will serialize (dump) all Annotation objects in Fedora.
An optional 'format' parameter to output the serialization
in different formats.
Format options are:
- nt (default)
- rdf/xml or xml
- rdf/json or json
- turtle or ttl
- n3
Python examples:
Funded by a grant from the Andrew W. Mellon Foundation, via the Open Annotation Collaboration.