Open Annotation in EPUB defines an adaptation of the W3C Open Annotation Data Model [[OA]] for representing annotations in an EPUB Publication.

The media type value for the annotation document defined in 3.2.1 Structure is subject to change prior to this specification becoming a recommendation.

Overview

Purpose and Scope

This specification, Open Annotation in EPUB, defines a profile of the W3C Open Annotation specification [[OA]] for the creation, distribution and rendering of annotations for EPUB® Publications.

Terminology

Refer to the EPUB Specifications for definitions of EPUB-specific terminology used in this document.

Annotation Document
The JSON document [[!RFC4627]] containing the collection of annotations, which follows the JSON-LD conventions [[!JSON-LD]].

Namespaces

The following namespaces are used in this specification:

Prefix Namespace Description
oa http://www.w3.org/ns/oa# The Open Annotation ontology
epub http://www.idpf.org/epub/vocab/oa# The Open Annotation in EPUB ontology
cnt http://www.w3.org/2011/content# Representing Content in RDF
dc http://purl.org/dc/elements/1.1/ Dublin Core Elements
dcterms http://purl.org/dc/terms/ Dublin Core Terms
dctypes http://purl.org/dc/dcmitype/ Dublin Core Type Vocabulary
schema http://schema.org/ Schema.org Vocabulary

Conformance

Content Conformance

A conformant Annotation Document MUST meet all of the following criteria:

Reading System Conformance

An EPUB Reading System MUST meet all of the following criteria for processing annotations:

This specification does not mandate how a Reading System is to present annotations to the User.

Publishing

Composition

Format

The Annotation Document MUST be serialized in a JSON document [[!RFC4627]] which follows the JSON-LD conventions [[!JSON-LD]].

The document MUST be valid to the schema provided in Appendix B.

Identifiers

To ensure global uniqueness across all Annotation Documents, identifiers for resources MUST be URIs [[!RFC3986]] and SHOULD either follow the HTTP/S [[!RFC2616]] or UUID URN [[!RFC4122]] schemes.

Identifiers of Collections and Annotations will be given as the value of an @id property in the Annotation Document.

Packaging

Standalone Collections

The need to package annotations independent of an EPUB Publication is important in many distribution scenarios: a publisher might sell annotations separately from their publications, Reading Systems need a way to synchronize annotations between devices, and so on.

To facilitate this model, the Annotation Document MAY be exchanged as a standalone file, provided the annotations it contains do not reference any local resources.

If any of the annotations in the Annotation Document reference local resources, however, the document MUST be zipped together with those resources for interchange.

The ZIP container used to package the Annotation Document with the local resources MUST conform to [[!ZIP APPNOTE 6.3.3]].

The Annotation Document MUST be stored in the root of the ZIP container and MUST have the file name "annotations.json".

Embedded Collections

It is not always feasible for the Annotation Document and local resources be separate from the EPUB Publication they annotate. A publisher might want to include one or more collections of annotations in the default distribution, for example.

To facilitate this model, the Annotation Document and all local resources MAY be included in the Rendition being annotated. If the annotations apply to more than one Rendition, the Annotation Document SHOULD be included in the Default Rendition.

When embedding the Annotation Document and local resources, they MUST NOT be included as a ZIP file in the EPUB Container [[!OCF301]].

Instead, the Annotation Document and all local resources are listed in the Package Document manifest [[!Publications301]] and included in the EPUB Container like any other Publication Resources.

Local Resources

Annotations MAY reference local resources additional to the Annotation Document itself. Such resources are referenced using relative IRIs [[!RFC3987]], and are resolved relative to the location of the Annotation Document.

All local resources MUST be valid Core Media Types [[!Publications301]].

Local resources have to be zipped with the Annotation Document when creating a standalone distribution file, as described in 3.1.3.1 Standalone Collections.

Remote Resources

Remotely-hosted resources MAY be referenced from annotations, but Reading Systems are not required to dereference and render such resources.

All remote resources MUST be valid Core Media Types [[!Publications301]].

Collections

Structure

The root object of the Annotation Document MUST contain exactly one object, which represents the collection of annotations.

The annotation collection object MUST have an "annotations" property, which defines the array of annotation objects for the collection. The annotations array typically includes one or more annotations, but MAY be empty. Refer to 4. Annotations for more information on defining individual annotations.

The annotation collection MUST have the following properties:

  • @context ‒ The mapping document that specifies the semantics of the JSON structure. MUST specify the value "http://www.idpf.org/epub/oa/1.0/context.json".
  • @id ‒ The identifier for the collection. Refer to 3.1.2 Identifiers for identifier requirements.
  • @type ‒ Conveys that the object is a collection of annotations. MUST specify the value "epub:AnnotationCollection".
  • annotations ‒ The set of annotations in the collection. The value MUST be a JSON array, which MAY be empty.

The Annotation Document's format MUST be identified by the media type "application/ld+json;profile=http://www.idpf.org/epub/oa/1.0/".

This specification extends the EPUB 3 Core Media Types [[!Publications301]] to allow Annotation Documents designated using this media type to travel in the EPUB Container [[!OCF301]].

The following example shows the default structure of an annotation collection.

{
   "@context": "http://www.idpf.org/epub/oa/1.0/context.json", 
   "@id": "http://example.org/annotations.json", 
   "@type": "epub:AnnotationCollection",
   "annotations": [ … ]
}

Metadata

Collection metadata MAY be included as additional properties of the collection object. The values of these properties are intended for presenting information about the collection to Users.

When providing collection metadata, annotation authors are strongly RECOMMENDED to utilize the following properties from DCMI Metadata Terms [[!DCTERMS]] where applicable:

  • dc:created
  • dc:creator
  • dc:description
  • dc:language
  • dcterms:modified
  • dc:publisher
  • dc:rights
  • dc:title

Additional metadata MAY be included, but Reading Systems processing of such metadata is OPTIONAL. Reading Systems SHOULD provide an interface for the User to view any metadata provided.

Metadata properties accept either a single value or an array of values. Reading Systems SHOULD make use of multiple values provided in different languages using the @value/@language construction from [[!JSON-LD]] in order to provide an accessible interface.

Annotations

Metadata

General

Each annotation object MUST include the following child properties:

  • @id ‒ The identifier for the annotation. Identifiers MUST be URIs and globally unique.
  • @type ‒ Identifies that the object is an annotation. MUST specify the value "oa:Annotation".
  • hasTarget ‒ The target of the annotation. MUST be a publication, as defined in 4.3.1 The hasTarget Property, or a segment thereof. An annotation MAY have more than one target, in which case the value of hasTarget is an array of publications or segments.

The provenance of the annotation SHOULD be identified in the annotation metadata, as detailed in 2.2 Annotation Provenance [[!OA]]. Likewise, the motivation SHOULD be identified, as detailed in 2.3 Motivations [[!OA]].

An annotation object MAY include additional properties defined in [[!OA]].

All properties accept either a single value or an array of values.

Target Audience

It is sometimes the case that annotations are intended for only a certain audience. For example, a teacher's guide might be expressed as a set of annotations intended only for the instructor.

To specify the intended audience of an annotation, Authors MAY use the audience property on an annotation. The use of the [[!schema.org]] Audience class and sub-classes, plus their properties, is RECOMMENDED with this property. Property names from these classes MUST be prefixed with "schema:".

The audience property MAY identify a single audience or an array of audiences.

If a Reading System provides the ability for the User to indicate their role, and recognizes the expressed audience, it MUST filter the annotations displayed to the User. In all other cases, Reading Systems MUST ignore this property.

For annotations intended for educational audiences, the [[schema.org]] EducationalAudience type is suggested, using the recommended terms from the EDUPUB Profile for the educationalRole property to identify the audience.

Body

Structure

Each annotation object MAY include a comment, called the body of the annotation. The annotation body is defined in a child hasBody property of the annotation object. If present, this property MUST reference an object consisting of the following properties:

  • format ‒ Identifies the media type of the body content in the chars property. For this version of this specification, the property MUST have the value "application/xhtml+xml".
  • @type ‒ A general specification of the type of content in the chars property. For this version of this specification, the property MUST have the value "dctypes:Text". (Note that this value is not a restriction on the [[!HTML5]] content that can be included in the chars property; the use of audio, video and images is valid in the fragment.)
  • chars ‒ the XHTML document fragment conforming to the requirements detailed in this section.

The language of the body SHOULD be identified in a child language property of the body object whose value MUST conform to [[!RFC5646]]. It is strongly RECOMMENDED that the language also be specified on the root element of the body fragment to ensure proper rendering in assistive technologies.

The annotation body MUST contain an [[!HTML5]] document fragment, using the XML serialization. The fragment root MUST be an [[!HTML5]] Flow Content element and the body fragment MUST be UTF-8 encoded [[!Unicode]].

The annotation body MUST NOT contain instances of the [[!HTML5]] script element and Reading Systems MUST NOT execute scripts embedded in the body, if encountered.

The restriction on scripting will be reviewed in a future version of this specification, after a security model is developed for Open Annotation.

Styling

As the annotation body does not allow linking to an external CSS style sheet, styling information has to be included by other means. Styling information MAY be be inlined using the [[!HTML5]] style attribute or by embedding a scoped style element.

CSS stylesheets referenced via an inline CSS @import rule MUST be UTF-8 encoded [[!Unicode]].

Reading Systems with a CSS viewport SHOULD support the EPUB 3 CSS Profile [[!ContentDocs301]] for rendering annotations.

Accessibility

Authors are strongly RECOMMENDED to identify the accessible qualities of the annotation body using the accessibilityFeature property of the [[!schema.org]] CreativeWork type (e.g., that alternative text is provided for embedded images). The value of the property MUST be a list, even if there is only one feature provided.

The other [[!schema.org]] accessibility properties MAY be specified, as appropriate.

The vocabulary of recommended terms to use with these properties is maintained at the W3C Web Schemas Wiki.

Targets

The hasTarget Property

The target of the annotation is identified in a child hasTarget property of the annotation object.

The target MUST be either an oa:SpecificResource with the EPUB Publication as the object of hasSource or another oa:Annotation. In the case of an EPUB Publication, the annotation MAY reference a fragment thereof as described in 4.3.5 Selectors.

The hasTarget property MAY identify a single target or an array of targets.

Publication Referencing

The publication or work referenced by the annotation MUST be identified in the hasSource property of the the target object. The object representing the publication MUST have a @type property with the value "dctypes:Text".

Additional metadata to aid in identification of the target publication SHOULD be given using any combination of the following optional properties:

  • @id - a URI that uniquely identifies the specific version of the EPUB Publication being annotated.
  • originURL - a URL of an actual location where the EPUB or more information about it (for example a "landing page") is available. The URL doesn't necessarily identify a specific version of the EPUB being annotated; if it does however, it can be the same URL as the value of the @id property.
  • uniqueIdentifier - the Unique Identifier of the target EPUB Publication [[!Publications301]].
  • dcterms:modified - the last modification date of the default Rendition of the target EPUB Publication, as part of the Release Identifier of the target EPUB Publication [[!Publications301]].
  • dc:identifier - any other identifier of the target publication, such as such as UUID, DOI, ISBN or ISSN. The value can be a string (representing a single identifier) of an array of strings (representing multiple identifiers).
  • any other property representing arbitrary metadata on the publication target, such as its title, creator name, etc.

Annotation Authors SHOULD provide as much as possible of the above information in the target object.

All properties accept either a single value or an array of values.

Specificity

Although an annotation always refers to a published work, or fragment thereof, its scope can vary from applying to a specific release of an EPUB Publication to applying to any published version of the work – even print. Annotation Authors MAY use the specificityLevel property of the target object to explicitly define the intended scope of the annotation. This property can have the following values:

  • release” – indicates that the annotation is relevant to a specific release of an EPUB Publication, based on the Publication's Release Identifier.
  • publication” – indicates that the annotation is relevant to any version of an EPUB Publication, based on the Publication's Unique Identifier.
  • work” – indicates that the annotation is relevant to the work, regardless of its publisher and version.

When the target object does not have a specificityLevel property, no default specificity level can be assumed and the Reading System SHOULD infer one from the available metadata, or negotiate with the user to come to the appropriate level.

Renditions

To handle multiple Renditions of an EPUB Publication in the Container, this specification adds the ability to select the specific Package Document [[!Publications301]] within the Container that evaluation of the fragment expression is to begin at.

The path to the package document is specified in an object of type epub:RenditionState (the value of the hasState property). It MUST have an opfPath property, which contains the path to the Package Document relative to the root of the OCF Container.

If an epub:RenditionState object is not specified, then any EPUB Canonical Fragment Identifiers are resolved starting at the Package Document of the Default Rendition.

The workflow that a Reading System SHOULD follow is:

  1. Determine the correct EPUB, given an identifier or the metadata from hasSource.
  2. Determine the correct Rendition, if there is an epub:RenditionState object.
  3. Determine the correct segment of the Rendition, if there is a oa:FragmentSelector that provides the CFI fragment (see Section 4.3.5.1).

Selectors

EPUB CFI Fragment Selector

If an annotation refers to a specific fragment of a resource within an EPUB Publication, that segment MUST be identified using the EPUB Canonical Fragment Identifiers (EPUB CFI) scheme [[!EPUB-CFI]].

Each annotation MAY include an oa:FragmentSelector object that specifies the EPUB CFI (the value of the hasSelector property). The type of selector is defined in the @type property, which MUST specify the value "oa:FragmentSelector".

The EPUB CFI in the value property of the oa:FragmentSelector object MUST NOT include a resource IRI [[!RFC3987]], only the fragment identifier excluding the initial hash (#).

Other Selectors

The Open Annotation framework allows for multiple selectors to be specified to provide robustness of the target anchoring. This version of the Open Annotation in EPUB specification does not provide guidance on how to use the multiplicity constructs [[!OA]] as currently there is not an accepted Selector for choosing a file within a containing resource, such as an HTML or image file within the EPUB container. A future version of this specification may specify how to define such selectors.

Styling

It is sometimes important to capture styling information for the target segments. For example, highlight colors might have meaning to the annotator, or the styling of the publication might make it difficult or impossible to see the default rendering of the target area. An additional style MAY be added by means of a styleClass property on the target and a styledBy property on the annotation itself that contains the stylesheet in a oa:CssStyle object.

The styleClass property MUST have the name of a CSS class defined in the stylesheet. The stylesheet is embedded in the same way as the body, and MUST have @type property with value "oa:CssStyle", and format property with the value "text/css". The stylesheet content is included as the value of the chars property of the object.

Annotating Annotations

An additional requirement, beyond annotating publications, is the ability to annotate other annotations. This allows for threaded conversations to occur, such as between teacher and student or between members of a reading group. The target of an annotation MAY be another annotation. In this case, the value of the hasTarget property MUST be the URI, given in @id, of the annotation being annotated. The motivation of the annotating annotation SHOULD be "oa:replying".

Examples

All examples use the same hypothetical publication of Alice in Wonderland, and are given in the collection structure with a single annotation.

Schema for JSON-LD representation

The JSON-LD representation schema for Annotation Documents is available at http://www.idpf.org/epub/oa/schema/oa-epub-schema.json.

Validation using this schema requires a processor that supports [[!JSON-Schema]].

Default Context description

{
   "@context": [
      "http://www.w3.org/ns/oa-context-20130208.json",
      {
         "epub": "http://www.idpf.org/epub/vocab/oa/#",
         "schema": "http://schema.org/",
         "annotations": {
            "@id": "epub:annotations",
            "@type": "@id",
            "@container": "@list"
         },
         "language": "dc:language",
         "opfPath": "epub:opfPath",
         "specificityLevel": "epub:specificityLevel",
         "originURL": "epub:originURL",
         "uniqueIdentifier": "epub:uniqueIdentifier",
         "accessibilityFeature": "schema:accessibilityFeature",
         "accessibilityHazard": "schema:accessibilityHazard",
         "accessibilityAPI": "schema:accessibilityAPI",
         "accessibilityControl": "schema:accessibilityControl",
         "audience": "schema:audience",
         "audienceType": "schema:audienceType"
      }
   ]
} 

Comparison to Open Annotation

This appendix summarizes the restrictions and specializations that this profile of Open Annotation introduces as compared to the parent specification [[OA]].

Acknowledgements and Contributors

EPUB has been developed by the International Digital Publishing Forum in a cooperative effort, bringing together publishers, vendors, software developers, and experts in the relevant standards.

The Open Annotations in EPUB 1.0 specification was prepared by the International Digital Publishing Forum's EPUB Working Group, operating under a continuation of the EPUB 3.0 charter approved by the membership in May, 2010 under the leadership of:

Active members of the working group at the time of publication were:

IDPF Members

Invited Experts/Observers