Open Annotation in EPUB

Draft Specification 28 May 2014

This version:

http://www.idpf.org/epub/oa/epub-oa-20140528.html

Latest version:

http://www.idpf.org/epub/oa/

Previous version:

http://www.idpf.org/epub/oa/epub-oa-20140325.html

Copyright © 2014 International Digital Publishing Forum™

All rights reserved. This work is protected under Title 17 of the United States Code. Reproduction and dissemination of this work with changes is prohibited except with the written permission of the International Digital Publishing Forum (IDPF).

EPUB® is a registered trademark of the International Digital Publishing Forum.

Editors

Romain Deltour, DAISY

Matt Garrish, Invited Expert

Markus Gylling, International Digital Publishing Forum (IDPF)

Rob Sanderson, Invited Expert

Status of this Document

This is a Draft Specification, produced by the IDPF EPUB 3 working group. This document may be updated, replaced, or rendered obsolete by other documents at any time.

In particular, the media type value for the annotation document defined in 3.3.1 Structure is subject to change prior to this specification becoming a recommendation.

Open issues in this draft

Table of Contents

1. Overview

1.1 Purpose and Scope

1.2 Terminology

1.3 Typographic Conventions

1.4 Conformance Statements

1.5 Namespaces

2. Conformance

2.1 Content Conformance

2.2 Reading System Conformance

3. Publishing

3.1 Introduction

3.2 Composition

3.2.1 Format

3.2.2 Identifiers

3.2.3 Packaging

3.2.3.1 Standalone Collections

3.2.3.2 Embedded Collections

3.2.3.3 Local Resources

3.2.3.4 Remote Resources

3.3 Collections

3.3.1 Structure

3.3.2 Metadata

4. Annotations

4.1 Metadata

4.1.1 General

4.1.2 Target Audience

4.2 Body

4.2.1 Structure

4.2.2 Styling

4.2.3 Accessibility

4.3 Targets

4.3.1 The hasTarget Property

4.3.2 Publication Referencing

4.3.3 Specificity

4.3.4 Renditions

4.3.5 Selectors

4.3.5.1 EPUB CFI Fragment Selector

4.3.5.2 Other Selectors

4.3.6 Styling

4.3.7 Annotating Annotations

Appendix A. Examples

Appendix B. Schema for JSON-LD representation

Appendix C. Default Context description

Appendix D. Comparison to Open Annotation

Appendix E. Acknowledgements and Contributors

References

Normative References

1. Overview

1.1 Purpose and Scope

This section is informative

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

1.2 Terminology

Please 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].

1.3 Typographic Conventions

The following typographic conventions are used in this specification:

markup

All markup (elements, attributes, properties), code (JavaScript, pseudo-code), machine processable values (string, characters, media types) and file names are in red-orange monospace font.

markup

Links to markup and code definitions are underlined and in red-orange monospace font. Only the first instance in each section is linked.

http://www.idpf.org/

URIs are in navy blue monospace font.

hyperlink

Hyperlinks are underlined and in blue.

[reference]

Normative and informative references are enclosed in square brackets.

Term

Terms defined in the Terminology are in capital case.

Informative markup examples are in monospace font.

NOTE

Informative notes are preceded by a "Note" header.

1.4 Conformance Statements

The keywords must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].

All sections of this specification are normative except for examples, or except for sections identified by the informative status label "This section is informative". The application of informative status to sections and appendices applies to all child content and subsections they may contain.

1.5 Namespaces

This section is informative

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

2. Conformance

2.1 Content Conformance

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

 It must be serialized as defined in 3.2.1 Format, and conform to the JSON-LD representation schema in Appendix B

 It must include exactly one collection conforming to the requirements in 3.3 Collections.

It must conform to the packaging requirements in 3.2.2 Packaging.

 Each annotation in the document:

2.2 Reading System Conformance

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

 It should provide a mechanism to export annotations conformant with this specification.

 It must provide a mechanism for the import of annotations conformant with this specification.

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

3. Publishing

3.1 Introduction

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

3.2 Composition

3.2.1 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.

3.2.2 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.

3.2.3 Packaging

3.2.3.1 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".

3.2.3.2 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.

3.2.3.3 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].

NOTE

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

3.2.3.4 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].

3.3 Collections

3.3.1 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:

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": [ … ]

}

3.3.2 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 [DCMI] where applicable:

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.

The following example shows typical metadata for an annotation collection.

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "dc:title": "Alice in Wonderland Annotations",

  "dc:publisher": "Example Organization",

  "dc:creator": "Anne O'Tater",

  "dcterms:modified": "2014-03-17T12:30:00Z",

  "dc:description": "Anne's collection of annotations on Alice in Wonderland",

  "dc:rights": [

    {"@value": "Quelques droits en Français", "@language": "fr"},

    {"@value": "Some Rights in English", "@language": "en"}

  ],

  "annotations": [ … ],

}

4. Annotations

4.1 Metadata

4.1.1 General

Each annotation object must include the following child properties:

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

An annotation object may include additional properties defined in [OpenAnnotation].

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

The following example shows typical provenance and motivation expressions for an annotation.

{

  "@id": "http://example.org/epub/annotation/1.json",

  "@type": "oa:Annotation",

  "motivatedBy": "oa:commenting",

  "annotatedBy": {

    "@id": "mailto:Anne@example.org",

    "@type": "foaf:Person",

    "name": "Anne O'Tater"

  },

  "annotatedAt": "2014-03-20T09:32:30Z",

  "hasTarget": { … },

  "hasBody": { … }

}

4.1.2 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 following example shows an annotation intended for use by teachers.

{

  "@id": "http://example.org/epub/annotation/1.json",

  "@type": "oa:Annotation",

  "audience" : {

    "@type" : "schema:EducationalAudience",

    "schema:educationalRole" : "teacher"

   }

  "hasTarget": { … },

  "hasBody": { … }

}

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.

NOTE

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.

4.2 Body

4.2.1 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:

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.

NOTE

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

The following example shows an annotation body, which will be referenced from the hasBody property of the annotation.

{

  "@type": "dctypes:Text",

  "format": "application/xhtml+xml",

  "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

  "language": "en"

}

4.2.2 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.

The following example shows a body with embedded style.

{

  "@type": "dctypes:Text",

  "format": "application/xhtml+xml",

  "chars": "<div style='font-family:sans-serif;' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

  "language": "en"

}

4.2.3 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 following example shows typical accessibility features for a body.

{

  "@id": "http://example.org/epub/annotation/1.json",

  "@type": "oa:Annotation",  

  "hasTarget": { … },

  "hasBody": {

    "@type": "dctypes:Text",

    "format": "application/xhtml+xml",

    "language": "en",

    "accessibilityFeature": ["alternativeText", "captions"]

  }

}

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.

4.3 Targets

4.3.1 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 2.6.3 Selectors.

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

4.3.2 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:

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.

The following example shows a set of source metadata for the target EPUB Publication in the hasSource property.

{

  "@type": "oa:SpecificResource",

  "hasSource": {

    "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub",

    "@type": "dctypes:Text",

    "uniqueIdentifier": "isbn:123456789x",

    "originURL": "http://www.example.com/publisher/book/",

    "dc:identifier": [

      "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",
     "isbn:123456789X"

    ],

    "dcterms:modified": "2011-01-01T12:00:00Z"

  }

}

4.3.3 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:

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.

The following example shows how an annotation that is specific to a work.

{

  "@type": "oa:SpecificResource",

  "specificityLevel": "work",

  "hasSource": {

    "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub",

    "@type": "dctypes:Text"

  }

}

4.3.4 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).

The following example shows the source EPUB Publication and Rendition for resolving EPUB CFIs.

{

  "@type": "oa:SpecificResource",

  "hasSource": {

    "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub",

    "@type": "dctypes:Text"

  },

  "hasState": {

    "@type": "epub:RenditionState",

    "opfPath": "/opfs/content.opf"

  }

}

4.3.5 Selectors

4.3.5.1 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 [EPUBCFI].

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 (#).

{

  "@type": "oa:SpecificResource",

  "hasSource": {

    "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub",

    "@type": "dctypes:Text"

  },

  "hasState": {

    "@type": "epub:RenditionState",

    "opfPath": "/opfs/content.opf"

  },

  "hasSelector": {

    "@type": "oa:FragmentSelector",

    "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

  }

}

4.3.5.2 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 [OpenAnnotation] 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.

4.3.6 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.

The following example shows a red border is to be applied to the target of the annotation.

{

  "@id": "http://example.org/epub/annotation/1.json",

  "@type": "oa:Annotation",

  "motivatedBy": "oa:commenting",

  "styledBy": {

    "@type": "oa:CssStyle",

    "format": "text/css",

    "chars": ".red { border: 1px solid red; }"

  },

  "hasTarget": {

    "@type": "oa:SpecificResource",

    "hasSelector": {

      "@type": "oa:FragmentSelector",

      "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

    },

    "hasSource": {

      "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub",

      "@type": "dctypes:Text"

    },

    "styleClass": "red"

  },

  "hasBody": { … }

}

4.3.7 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".     

The following example shows an annotation (2.json) with another annotation (1.json) as its target.

{

  "@id": "http://example.org/epub/annotation/2.json",

  "@type": "oa:Annotation",

  "motivatedBy" : "oa:replying",

  "hasTarget": "http://example.org/epub/annotation/1.json",

  "hasBody": { … }

}


 

Appendix A. Examples

This appendix is informative

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

  1. Commentary Annotation on Publication with URI

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSource": {

          "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub", 

          "@type": "dctypes:Text"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Commentary Annotation on Publication without Identifying URI

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Collection Metadata

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "dc:title": "Alice in Wonderland Annotations",

  "dc:publisher": "Example Organization",

  "dc:creator": "Anne O'Tater",

  "dcterms:modified": "2014-03-17T12:30:00Z",

  "dc:description": "Anne's collection of annotations on Alice in Wonderland",

  "dc:rights": [

    {

      "@value": "Quelques droits en Français",

      "@language": "fr"

    },

    {

      "@value": "Some Rights in English",

      "@language": "en"

    }

  ],

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Annotation Provenance

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "annotatedBy": {

        "@id": "mailto:Anne@example.org",

        "@type": "foaf:Person",

        "name": "Anne O'Tater"

      },

      "annotatedAt": "2014-03-20T10:40:08Z",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Annotation with Ancillary Resources in the Zip

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland! <img src='/imgs/heart.jpg'/></div>"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

 

  1. Reading Location Bookmarking

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "http://example.org/epub/annotation/1.json",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSelector": {

          "@type": "oa:FragmentSelector",

          "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

        }, 

       "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "motivatedBy": "oa:bookmarking"

    }

  ]

}

  1. Text Selection Highlighting

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "http://example.org/epub/annotation/1.json",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSelector": {

          "@type": "oa:FragmentSelector",

          "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

        }, 

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "motivatedBy": "oa:highlighting"

    }

  ]

}

  1. Commentary on Text Selection

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "http://example.org/epub/annotation/1.json",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSelector": {

          "@type": "oa:FragmentSelector",

          "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

        },

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love this part of the text</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Specifying a Rendition

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "http://example.org/epub/annotation/1.json",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSelector": {

          "@type": "oa:FragmentSelector",

          "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

        },

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        },

        "hasState": {

          "@type": "epub:RenditionState",

          "opfPath": "/opfs/content.opf"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love this part of the text</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Annotating Multiple Targets

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": [

        {

          "@type": "oa:SpecificResource",

          "hasSelector": {

            "@type": "oa:FragmentSelector",

            "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

          },

          "hasSource": {

            "@type": "dctypes:Text",

            "uniqueIdentifier": "isbn:123456789x",

            "originURL": "http://www.example.com/publisher/book/",

            "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

            "dcterms:modified": "2011-01-01T12:00:00Z"

          }

        },

        {

          "@type": "oa:SpecificResource",

          "hasSelector": {

            "@type": "oa:FragmentSelector",

            "value": "epubcfi(/8/2[chap02ref]!/4[body02]/12[para06]/10:20)"

          },

          "hasSource": {

            "@id": "http://www.example.org/ebooks/A1B0D67E-2E81-4DF5/v2.epub",

            "@type": "dctypes:Text"

          }

        }

      ], 

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love the Cheshire Cat in these two sections</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Styling of Selection

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "styledBy": {

        "@type": "oa:CssStyle",

        "format": "text/css",

        "chars": ".red { border: 1px solid red; }"

      }, 

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSelector": {

          "@type": "oa:FragmentSelector",

          "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

        },

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        },

        "styleClass": "red"

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love this part of the text</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Styling of Comment

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSelector": {

          "@type": "oa:FragmentSelector",

          "value": "epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)"

        },

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div style='font-family:sans-serif;color:red;' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

        "language": "en"

      },

      "motivatedBy": "oa:commenting"

    }

  ]

}

  1. Tagging

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "@type": "oa:Annotation",

      "hasTarget": {

        "@type": "oa:SpecificResource",  

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<span xmlns='http://www.w3.org/1999/xhtml'>fantasy</span>"

      },

      "motivatedBy": "oa:tagging"

    }

  ]

}

  1. Specifying Intended Audience(s)

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:B81AF8C4-B04A-4D3D-B1D3-23F7C02E56BB",

      "@type": "oa:Annotation",

      "motivatedBy": "oa:commenting",

      "audience" : [
       {

          "@type" : "schema:EducationalAudience",

          "schema:educationalRole" : "teacher"

        },  

        {

          "@type" : "schema:Audience",

          "schema:audienceType" : "scientist"

        }

      ],

      "hasTarget": {

        "@type": "oa:SpecificResource",

        "hasSource": {

          "@type": "dctypes:Text",

          "uniqueIdentifier": "isbn:123456789x",

          "originURL": "http://www.example.com/publisher/book/",

          "dc:identifier": "urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809",

          "dcterms:modified": "2011-01-01T12:00:00Z"

        }

      },

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<div xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>I love Alice in Wonderland</div>",

        "language": "en"

      }

    }

  ]

}

  1. Replying to an Annotation

{

  "@context": "http://www.idpf.org/epub/oa/1.0/context.json",

  "@id": "http://example.org/epub/annotations.json",

  "@type": "epub:AnnotationCollection",

  "annotations": [

    {

      "@id": "urn:uuid:B81AF8C4-B04A-4D3D-B1D3-23F7C02E56BB",

      "@type": "oa:Annotation",

      "motivatedBy": "oa:replying",

      "hasTarget": "urn:uuid:E7E3799F-3CD5-4F69-87C6-5478B22873D6",

      "hasBody": {

        "@type": "dctypes:Text",

        "format": "application/xhtml+xml",

        "chars": "<span xmlns='http://www.w3.org/1999/xhtml'>I agree!</span>"

      }

    }

  ]

}

Appendix B. 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 [JSONSchema].

Appendix C. 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"

    }

  ]

}

Appendix D. Comparison to Open Annotation

This appendix is informative

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

Appendix E. 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

References

Normative References

[ContentDocs301] EPUB Content Documents 3.0.1.

[DCMI] DCMI Metadata Terms.

[EPUBCFI] EPUB Canonical Fragment Identifier (epubcfi) Specification.

[HTML5] HTML5: A vocabulary and associated APIs for HTML and XHTML.

[JSON-LD] JSON-LD 1.0: A JSON-based Serialization for Linked Data. Manu Sporny, et al. 16 January 2014.

[JSONSchema] JSON Schema: core definitions and terminology.

[OCF301] Open Container Format 3.0.1.

[OpenAnnotation] Open Annotation Data Model.

[Publications301] EPUB Publications 3.0.1.

[RFC2616] Hypertext Transfer Protocol -- HTTP/1.1 (RFC 2616). R. Fielding, et al. June, 1999.

[RFC3986] Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). Berners-Lee, et al. January 2005.

[RFC3987] Internationalized Resource Identifiers (IRIs) (RFC 3987) . M Duerst, et al. January 2005.

[RFC4122] A Universally Unique IDentifier (UUID) URN Namespace (RFC4122). P. Leach, et al. July 2005.

[RFC4627] The application/json Media Type for JavaScript Object Notation (JSON) (RFC 4627). D. Crockford. July 2006.

[RFC5646] Tags for Identifying Languages (RFC 5646) . A. Phillips, M. Davis. September 2009.

[schema.org] schema.org.

[Unicode] The Unicode Consortium. The Unicode Standard..

[ZIP APPNOTE 6.3.3] ZIP File Format Specification. September 28, 2007. PKWARE, Inc.