The Readium Web Publication Manifest defines a shared external context document hosted by the Readium Foundation and based primarily on schema.org and its extensions.
This context is meant primarily to:
- align the Web Publication Manifest with the Web by adopting schema.org and its extensions
- provide compatibility with EPUB 3.2 by providing equivalent metadata elements based on schema.org
Name | URI | Description | Required? |
---|---|---|---|
Default Context | https://readium.org/webpub-manifest/context.jsonld | Default context definition used in every Readium Web Publication Manifest. | Yes |
A Web Publication Manifest must contain a single title using the title
element:
"title": "Moby-Dick"
In addition to a simple string representation, the title
element also supports alternate representations of the same string in different scripts and languages.
To provide these alternate representations, an object may be used instead of a string, where each key identifies a language/script and must be a valid BCP 47 language tag:
"title": {
"fr": "Vingt mille lieues sous les mers",
"en": "Twenty Thousand Leagues Under the Sea",
"ja": "海底二万里"
}
In addition to the title
element, the manifest may also contain an optional subtitle
element with exactly the same syntax.
"title": "Flatland"
"subtitle": "A Romance of Many Dimensions"
The manifest may also contain a sortAs
element to provide a single sortable string, used by a client to organize a collection of publications:
"title": "A Tale of Two Cities"
"sortAs": "Tale of Two Cities, A"
A Web Publication Manifest should contain an identifier. The identifier must be a valid URI:
"identifier": "http://example.com/publication"
The default context for the Web Publication Manifest provides a number of elements to indicate the nature of a contributor: author
, translator
, editor
, artist
, illustrator
, letterer
, penciler
, colorist
, inker
and narrator
.
In addition to these elements, it also provides a generic term for contributors: contributor
.
A Web Publication Manifest should contain one or more contributors.
The most straightforward expression of a contributor is through a simple string:
"author": "James Joyce"
Each element can also contain multiple contributors using a simple array:
"artist": ["Shawn McManus", "Colleen Doran", "Bryan Talbot"]
In addition to a simple string representation, each contributor can also be represented using an object using the following elements: name
, sortAs
and identifier
.
When an object is used, it must contain at least name
.
It behaves like the title
element and allows either a simple strings, or representations in multiple languages and scripts of a contributor's name:
"author": {
"name": {
"ru": "Михаил Афанасьевич Булгаков",
"en": "Mikhail Bulgakov",
"fr": "Mikhaïl Boulgakov"
}
}
The contributor object may also contain a sortAs
element to provide a single sortable string, used by a client to organize a collection of publications:
"author": {
"name": "Marcel Proust",
"sortAs": "Proust, Marcel"
}
Finally, the object may also contain an identifier
. The identifier
must be a URI.
ISNI (http://isni.org) is the preferred authority, but other sources may also be used:
"author": {
"name": "Jules Amédée Barbey d'Aurevilly",
"sortAs": "Barbey d'Aurevilly, Jules Amédée",
"identifier": "http://isni.org/isni/0000000121317806"
}
If none of the elements available are specific enough, a contributor
element may be used instead.
The contributor
element should be used with an object that contains a role
.
All values for the role
element should be based on MARC relator codes:
"contributor": {
"name": "Lou Reed",
"role": "sng"
}
In order to indicate its primary language, a Web Publication Manifest should use a language
element. Its value must be a valid BCP 47 language tag.
"language": "en"
If a publication has more than one primary language (a bilingual edition for example), the language
element may contain an array of values:
"language": ["en", "fr", "ja"]
A Web Publication Manifest may contain a description of the publication in plain text using the description
element:
"description": "The story of two gnomes, discussing the meaning of life in a Scandivanian garden."
A Web Publication Manifest may list one or more publishers using the publisher
element.
To provide even more details, it's also possible to use the imprint
element that behaves exactly like publisher
but provides a complementary information.
The most straightforward expression is through a simple string:
"publisher": "Literary Fiction Ltd."
"imprint": "World Literature"
This element also allows a more complex representation using an object and the following elements: name
, sortAs
, identifier
. The semantics and syntax are identical to contributors:
"publisher": {
"name": "The Science Fiction Company",
"sortAs": "Science Fiction Company, The",
"identifier": "http://example.com/publisher/TheScienceFictionCompany"
}
Multiple publishers can be listed in this element using the string or object representations.
A Web Publication Manifest may contain a publication date using the published
element. The publication date must be a valid ISO 8601 date.
"published": "2016-09-02"
Publications can be updated and to identify each specific version, the manifest should also contain a modified
element containing the timestamp when the publication was last modified expressed as an ISO 8601 time and date:
"modified": "2016-02-22T11:31:38Z"
A Web Publication Manifest may also provide one or more subjects using the subject
element:
"subject": "Historical Fiction"
Multiple subjects are listed using an array:
"subject": ["Science Fiction", "Fantasy"]
Subjects can also be expressed using an object with the following elements: name
, sortAs
, code
and scheme
.
name
is meant to provide a human readable string for the subject, while sortAs
is meant to provide a string that a machine can sort:
"subject": {
"name": "Manga: Shonen",
"sortAs": "Shonen"
}
In many fields and territories, a number of controlled vocabularies are in use to identify subjects. For example THEMA is used in the publishing industry to provide an international subject scheme.
To indicate that a subject belongs to a particular scheme, the scheme
element is available. The scheme
must be a URI.
The code
element is available to provide the string that identifies the subject in a given scheme:
"subject": {
"name": "Manga: Shonen",
"sortAs": "Shonen",
"scheme": "http://www.editeur.org/151/Thema/",
"code": "XAMG"
}
A Web Publication Manifest may indicate that it belongs to one or multiple collections/series.
collection
and series
behave the same way, the most straightforward way to indicate that a publication belongs to a collection/series is through a simple string:
"belongsTo": {
"collection": "Mysteries from Another Time",
"series": "The Zombie Detective"
}
In order to provide more information about a specific collection/series, an object can also be used instead of a string.
To provide a name and a sortable string, collection
and series
support both name
and sortAs
:
"belongsTo": {
"series": {
"name": "The Zombie Detective",
"sortAs": "Zombie Detective, The"
}
}
A collection/series can also have an identifier, provided using the identifier
element. The identifier must be a URI:
"belongsTo": {
"series": {
"name": "The Zombie Detective",
"sortAs": "Zombie Detective, The",
"identifier": "http://www.example.com/series/TheZombieDetective"
}
}
Finally, series/collection can be ordered. To provide the position of the current publication in a series/collection, the position
element can be used.
A position can be either an integer or a float where the value is greater than zero.
"belongsTo": {
"series": {
"name": "The Zombie Detective",
"sortAs": "Zombie Detective, The",
"identifier": "http://www.example.com/series/TheZombieDetective",
"position": 4
}
}
To properly browse through a publication, a User Agent needs to know its progression direction.
A manifest may express this information using readingProgression
.
It allows the following values: ltr
(left to right), rtl
(right to left), ttb
(top to bottom), btt
(bottom to top) and auto
.
It defaults to auto
when no value is set.
To indicate the length of a publication, a Web Publication Manifest may include the duration
and numberOfPages
terms.
duration
is expressed in seconds using a float (number in JSON), while numberOfPages
is an integer.
"duration": 5467
"numberOfPages": 178
In addition to these two properties, abridged
is used to indicate an abridged edition of a publication. This is expressed using a boolean.
"abridged": true
In order to document its accessibility metadata, a Web Publication Manifest should include an accessibility
object.
This accessibility
object may contain the following properties: conformsTo
, certification
, accessMode
, accessModeSufficient
, feature
, hazard
and summary
.
conformsTo
contains one or more URI, meant to convey that a publication conforms to a specific accessibility profile.
This specification identifies the following profiles:
Profile | URI |
---|---|
EPUB Accessibility 1.0 - WCAG 2.0 Level A | http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-a |
EPUB Accessibility 1.0 - WCAG 2.0 Level AA | http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa |
EPUB Accessibility 1.0 - WCAG 2.0 Level AAA | http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aaa |
The certification
object contains information about the certification process of a publication.
certifiedBy
identifies the person or the organization that conducted the certification.
credential
provides additional credentials regarding the ability of the certifier to conduct an accessibility report.
report
points to one or more accessibility reports for the publication, using a list of URL.
"certification": {
"certifiedBy": "Tom Smith",
"report": "https://example.com/report/a11y",
"credential": "Certified by Benetech"
}
accessMode
and accessModeSufficient
are meant to list the human sensory perceptual systems or cognitive faculties necessary to access a given publication.
While accessMode
provides a complete list, accessModeSufficient
is focused on list of single or combined accessModes that are sufficient to understand all the intellectual content of a resource.
Both properties are controlled by external vocabularies maintained by the W3C.
Property | Controlled vocabulary |
---|---|
accessMode |
https://www.w3.org/2021/a11y-discov-vocab/latest/#accessMode-vocabulary |
accessModeSufficient |
https://www.w3.org/2021/a11y-discov-vocab/latest/#accessModeSufficient-vocabulary |
"accessibility": {
"accessMode": ["textual", "visual"],
"accessModeSufficient": [
["textual", "visual"],
"textual"
],
"feature": ["alternativeText"]
}
feature
and hazard
provide a list of potential accessibility features or hazards for a publication.
Both properties are controlled by external vocabularies maintained by the W3C.
Property | Controlled vocabulary |
---|---|
feature |
https://www.w3.org/2021/a11y-discov-vocab/latest/#accessibilityFeature-vocabulary |
hazard |
https://www.w3.org/2021/a11y-discov-vocab/latest/#accessibilityHazard-vocabulary |
"accessibility": {
"feature": [
"alternativeText",
"displayTransformability",
"readingOrder",
"structuralNavigation",
"tableOfContents"
],
"hazard": ["none"]
}
summary
is meant to convey additional information about the accessibility of a publication that cannot be expressed using conformsTo
, certification
, accessMode
, accessModeSufficient
, feature
or hazard
.
"summary": "The publication is recorded by a professional narrator."
The default context is implemented in the core JSON Schema for the Readium Web Publication Manifest and should be used as a reference as well.
The JSON Schema for metadata is under version control at https://github.com/readium/webpub-manifest/blob/master/schema/metadata.schema.json
For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resource: https://readium.org/webpub-manifest/schema/publication.schema.json
{
"@context": "https://readium.org/webpub-manifest/context.jsonld",
"metadata": {
"@type": "http://schema.org/Book",
"identifier": "urn:isbn:9780000000001",
"title": "Moby-Dick",
"author": "Herman Melville",
"language": "en",
"publisher": "Whale Publishing Ltd.",
"modified": "2016-02-18T10:32:18Z"
},
"links": [
{"rel": "self", "href": "http://example.org/manifest.json", "type": "application/webpub+json"},
{"rel": "alternate", "href": "http://example.org/publication.epub", "type": "application/epub+zip"}
],
"readingOrder": [
{"href": "cover.jpg", "type": "image/jpeg", "rel": "cover"},
{"href": "map.svg", "type": "image/svg+xml", "title": "Map"},
{"href": "c001.html", "type": "text/html", "title": "Chapter 1"},
{"href": "c002.html", "type": "text/html", "title": "Chapter 2"}
],
"resources": [
{"href": "style.css", "type": "text/css"},
{"href": "whale.jpg", "type": "image/jpeg"},
{"href": "boat.svg", "type": "image/svg+xml"},
{"href": "notes.html", "type": "text/html"}
]
}
If we use another example with more complex metadata expression and an extension:
{
"@context": "https://readium.org/webpub-manifest/context.jsonld",
"metadata": {
"@type": "http://schema.org/Book",
"identifier": "urn:isbn:9780000000002",
"title": {
"en": "A Journey into the Center of the Earth",
"fr": "Voyage au centre de la Terre"
},
"sortAs": "Journey into the Center of the Earth, A",
"author": {
"name": "Jules Verne",
"identifier": "http://isni.org/isni/0000000121400562",
"sortAs": "Verne, Jules"
},
"translator": "Frederick Amadeus Malleson",
"language": ["en", "fr"],
"publisher": "SciFi Publishing Inc.",
"modified": "2016-02-22T11:31:38Z",
"description": "The story involves German professor Otto Lidenbrock who believes there are volcanic tubes going toward the centre of the Earth. He, his nephew Axel, and their guide Hans descend into the Icelandic volcano Snæfellsjökull, encountering many adventures, including prehistoric animals and natural hazards, before eventually coming to the surface again in southern Italy, at the Stromboli volcano.",
"schema:isFamilyFriendly": true,
"belongsTo": {
"series": {
"name": "The Extraordinary Voyages",
"position": 3
},
"collection": "SciFi Classics"
}
}
}
In order to convert EPUB packages into a Readium Web Publication Manifest, we've documented how each metadata item listed in the default context is mapped to an equivalent in EPUB 2.x or 3.x.
This live document is available at: https://readium.org/architecture/streamer/parser/metadata