Draft Specification 23 July 2015
This version:
http://www.idpf.org/epub/oa/epub-oa-20150723.html
Latest version:
Previous version:
http://www.idpf.org/epub/oa/epub-oa-20150706.html
Copyright © 2014-2015 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
2.2 Reading System Conformance
3.2.3.1 Standalone Collections
4.3.5.1 EPUB CFI Fragment Selector
Appendix B. Schema for JSON-LD representation
Appendix C. Default Context description
Appendix D. Comparison to Open Annotation
Appendix E. Acknowledgements and Contributors
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.
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].
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.
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.
This section is informative
The following namespaces are used in this specification:
Prefix |
Namespace |
Description |
oa |
||
epub |
The Open Annotation in EPUB ontology |
|
cnt |
||
dc |
||
dcterms |
||
dctypes |
||
schema |
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:
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, which includes both annotations provided from an external source, as well as annotations embedded within an EPUB Publication.
This specification does not mandate how a Reading System is to present annotations to the User.
This specification defines an adaptation of the W3C Open Annotation Data Model [OpenAnnotation] for representing annotations in an EPUB Publication.
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.
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.
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".
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.
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.
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].
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": [ … ]
}
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": [ … ],
}
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:[email protected]",
"@type": "foaf:Person",
"name": "Anne O'Tater"
},
"annotatedAt": "2014-03-20T09:32:30Z",
"hasTarget": { … },
"hasBody": { … }
}
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.
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"
}
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"
}
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.
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.
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"
}
}
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"
}
}
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:
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"
}
}
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)"
}
}
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.
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": { … }
}
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": { … }
}
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.
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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:[email protected]",
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
]
}
{
"@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"
}
}
]
}
{
"@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>"
}
}
]
}
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].
{ "@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", "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" } ] } |
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].
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
[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.