diff --git a/README.md b/README.md index aa4038d..18e957e 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ W3C has recently provided a definition for a [Web Publication](https://w3c.githu > A **Web Publication (WP)** is a collection of one or more constituent resources, organized together in a uniquely identifiable grouping, and presented using standard Open Web Platform technologies. It also provides a definition for a manifest in the context of a Web Publication: -> [...] **manifest** refers to an abstract means to contain information necessary to the proper management, rendering, and so on, of a publication. This is opposed to metadata that contains information on the content of the publication like author, publication date, and so on. The precise format of how such a manifest is stored is not considered in this document. +> [...] **manifest** refers to an abstract means to contain information necessary to the proper management, rendering, and so on, of a publication. The Readium Web Publication Manifest is an attempt to standardize a JSON based manifest format that follows both definitions. @@ -319,7 +319,7 @@ Link Objects in `readingOrder`, `resources` or `links` can be identified as such All Link Objects containing the `cover` link relation must reference an image directly. They should include a `height` and `width` to facilitate how they are processed by User Agents. -This specification recommends using one of the following media types: `image/jpeg`, `image/png`, `image/gif`, `image/webp` or `image/svg+xml`. +This specification recommends using one of the following media types: `image/jpeg`, `image/png`, `image/gif`, `image/avif` or `image/svg+xml`. *Example 8: Reference to a cover* @@ -348,10 +348,10 @@ The initial registry, contains the following profiles: | Name | Description | | ----- | ------------ | -| [EPUB Profile](profiles/epub.md) | A profile for EPUB content transformed to Web Publications. | | [Audiobook Profile](profiles/audiobook.md) | A profile for Audiobooks. | | [Divina Profile](profiles/divina.md) | A profile for Digital Visual Narrative publications (comics, manga and bandes dessinées). | -| [PDF Profile](profiles/pdf.md) | A profile for PDF documents integrated into Web Publications. | +| [EPUB Profile](profiles/epub.md) | A profile for EPUB publications served as Web Publications. | +| [PDF Profile](profiles/pdf.md) | A profile for PDF documents served as Web Publications. | ## 9. Packaging diff --git a/context.jsonld b/context.jsonld index a00cc04..89c9350 100644 --- a/context.jsonld +++ b/context.jsonld @@ -14,6 +14,7 @@ "@container": "@language" }, "sortAs": "http://schema.org/alternateName", + "layout": "http://www.idpf.org/2013/rendition#layout", "accessibility": "@nest", "summary": "http://schema.org/accessibilitySummary", "accessMode": "http://schema.org/accessMode", diff --git a/contexts/default/README.md b/contexts/default/README.md index 84628b6..e6a6032 100644 --- a/contexts/default/README.md +++ b/contexts/default/README.md @@ -15,7 +15,7 @@ Default Context | [https://readium.org/webpub-manifest/context.jsonld](https://r ## Title -A Web Publication Manifest must contain a single title using the `title` element: +A Web Publication Manifest must contain a single title using the `title` element: ```json "title": "Moby-Dick" @@ -33,14 +33,14 @@ To provide these alternate representations, an object may be used instead of a s } ``` -In addition to the `title` element, the manifest may also contain an optional `subtitle` element with exactly the same syntax. +In addition to the `title` element, the manifest may also contain an optional `subtitle` element with exactly the same syntax. ```json "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: +The manifest may also contain a `sortAs` element to provide a single sortable string, used by a client to organize a collection of publications: ```json "title": "A Tale of Two Cities" @@ -49,12 +49,33 @@ The manifest may also contain a `sortAs` element to pro ## Identifier -A Web Publication Manifest should contain an identifier. The identifier must be a valid URI: +A Web Publication Manifest should contain an identifier. The identifier must be a valid URI: ```json "identifier": "http://example.com/publication" ``` +## Layout and reading progression + +Publications come in all shapes and forms but when it comes to publications that are primarily made of text and visuals, we can organize them in three main categories: + +- Reflowable publications, where users are free to change the text and layout however they prefer. +- Fixed layout publications, where each resource is a "page" and may be presented side by side with another resource in a "spread". +- Scrolled publications, where displaying the publication in a continuous scroll is meaningful and resources are usually fit to the width of the viewport + +In order to convey this information, a Web Publication Manifest may include a `layout` property with one of the following values: + +| Value | Description | Formats | +| ----- | ----------- | ------- | +| `reflowable` | Reading systems are free to adapt text and layout entirely based on user preferences. | EPUB | +| `fixed` | Each resource is a "page" where both dimensions are usually contained in the device's viewport. Based on user preferences, the reading system may also display two resources side by side in a spread. | Divina, Fixed Layout EPUB or PDF +| `scrolled` | Resources are displayed in a continuous scroll, usually by filling the width of the viewport, without any visible gap between between spine items. | Scrolled Divina | + +To provide a number of affordances (taps, gestures, keyboard events), reading systems also need to know the reading progression. + +For reflowable and fixed layout publications, a manifest may express this information using `readingProgression`. + +It allows the following values: `ltr` (left to right, default value) and `rtl` (right to left). ## Contributors @@ -62,7 +83,7 @@ The default context for the Web Publication Manifest provides a number of elemen In addition to these elements, it also provides a generic term for contributors: `contributor`. -A Web Publication Manifest should contain one or more contributors. +A Web Publication Manifest should contain one or more contributors. The most straightforward expression of a contributor is through a simple string: @@ -113,7 +134,7 @@ ISNI (http://isni.org) is the preferred authority, but other sources may also be } ``` -If none of the elements available are specific enough, a `contributor` element may be used instead. +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](https://www.loc.gov/marc/relators/relaterm.html): @@ -127,13 +148,13 @@ All values for the `role` element should be based on [MARC relator codes](https: ## Language -In order to indicate its primary language, a Web Publication Manifest should use a `language` element. Its value must be a valid [BCP 47](https://tools.ietf.org/html/bcp47) language tag. +In order to indicate its primary language, a Web Publication Manifest should use a `language` element. Its value must be a valid [BCP 47](https://tools.ietf.org/html/bcp47) language tag. ```json "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: +If a publication has more than one primary language (a bilingual edition for example), the `language` element may contain an array of values: ```json "language": ["en", "fr", "ja"] @@ -141,7 +162,7 @@ If a publication has more than one primary language (a bilingual edition for exa ## Description -A Web Publication Manifest may contain a description of the publication in plain text using the `description` element: +A Web Publication Manifest may contain a description of the publication in plain text using the `description` element: ```json "description": "The story of two gnomes, discussing the meaning of life in a Scandivanian garden." @@ -149,7 +170,7 @@ A Web Publication Manifest may contain a description of ## Publisher -A Web Publication Manifest may list one or more publishers using the `publisher` element. +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. @@ -175,7 +196,7 @@ Multiple publishers can be listed in this element using the string or object rep ## Publication date -A Web Publication Manifest may contain a publication date using the `published` element. The publication date must be a valid ISO 8601 date. +A Web Publication Manifest may contain a publication date using the `published` element. The publication date must be a valid ISO 8601 date. ```json "published": "2016-09-02" @@ -183,7 +204,7 @@ A Web Publication Manifest may contain a publication da ## Modification date -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: +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: ```json "modified": "2016-02-22T11:31:38Z" @@ -191,7 +212,7 @@ Publications can be updated and to identify each specific version, the manifest ## Subjects -A Web Publication Manifest may also provide one or more subjects using the `subject` element: +A Web Publication Manifest may also provide one or more subjects using the `subject` element: ```json "subject": "Historical Fiction" @@ -239,7 +260,7 @@ This document identifies the following subject schemes along with a recommended ## Collections & series -A Web Publication Manifest may indicate that it belongs to one or multiple collections/series. +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: @@ -291,19 +312,9 @@ A position can be either an integer or a float where the value is greater than z } ``` -## Reading progression direction - -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. - ## Duration and number of pages -To indicate the length of a publication, a Web Publication Manifest may include the `duration` and `numberOfPages` terms. +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. @@ -320,9 +331,9 @@ In addition to these two properties, `abridged` is used to indicate an abridged ## Accessibility metadata -In order to document its accessibility metadata, a Web Publication Manifest should include an `accessibility` object. +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`. +This `accessibility` object may contain the following properties: `conformsTo`, `certification`, `accessMode`, `accessModeSufficient`, `feature`, `hazard` and `summary`. ### Conformance diff --git a/guidelines/divina-guidelines.md b/experimental/divina-guidelines.md similarity index 98% rename from guidelines/divina-guidelines.md rename to experimental/divina-guidelines.md index 6978745..5ba6c4a 100644 --- a/guidelines/divina-guidelines.md +++ b/experimental/divina-guidelines.md @@ -1,4 +1,4 @@ -# DiViNa guidelines +# Advanced Divina guidelines ## Guidelines relative to presentation hints diff --git a/experimental/presentation.md b/experimental/presentation.md new file mode 100644 index 0000000..995999f --- /dev/null +++ b/experimental/presentation.md @@ -0,0 +1,134 @@ +# Advanced Divina Presentation Hints + +The Presentation Hints extension defines a number of hints for User Agents about the way content should be presented to the user. + +## 1. Presentation Hints in `metadata` + +In order to provide publication-wide Presentation Hints, this extension introduces a new element in the `metadata` object of [the Readium Web Publication Manifest](https://readium.org/webpub-manifest): + +| Key | Semantics | Type | +| ----- | --------- | -------- | +| `presentation` | Publication-wide presentation hints. | Object | + +The following elements may be included in `presentation`: + +- [`clipped`](#clipped) +- [`fit`](#fit) +- [`orientation`](#orientation) + +## 2. Presentation Hints as Link Properties + +In addition to publication-wide hints, this extension defines a number of Link Properties to provide resource-level hints in `readingOrder` or `resources`. + +The following elements may be included in `properties`: + +- [`clipped`](#clipped) +- [`fit`](#fit) +- [`orientation`](#orientation) + +## 3. Properties + +### clipped + +The `clipped` property is meant to adapt visual resources to any given viewport ratio. The clipped areas must not contain information which are mandatory for the comprehension of the resource. + +| Key | Semantics | Type | Values | Default | +| ----- | --------- | -------- | --------- | ------- | +| `clipped` | Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped. | Boolean | `true` or `false` | `false` | + +*In this example, all resources are scaled to fit the viewport height and clipped to fit different viewport widths. It behaves like turbomedia.* + +```json +"metadata": { + "layout": "scrolled", + "presentation": { + "fit": "height", + "clipped": true + } +} +``` + +*In this example, a specific resource is scaled to fit the viewport width and clipped to fit different viewport heights.* + +```json +"readingOrder": [ + { + "href": "image1.avif", + "type": "image/avif", + "properties": { + "fit": "width", + "clipped": true + } + } +] +``` + +### fit + +| Key | Semantics | Type | Values | Default | +| ----- | --------- | -------- | --------- | ------- | +| `fit` | Specifies constraints for the presentation of a linked resource within the viewport. | String | `contain`, `cover`, `width` or `height` | `contain` | + +| Value | Definition | +| ------- | ---------- | +| `contain` | The content is centered and scaled to fit both dimensions into the viewport. | +| `cover` | The content is centered and scaled to fill the viewport. | +| `width` | The content is centered and scaled to fit the viewport width. | +| `height` | The content is centered and scaled to fit the viewport height. | + +*In this example, a specific resource is scaled to fit the viewport.* + +```json +"readingOrder": [ + { + "href": "image1.avif", + "type": "image/avif", + "properties": { + "fit": "contain" + } + } +] +``` + +### orientation + +| Key | Semantics | Type | Values | Default | +| ----- | --------- | -------- | --------- | ------- | +| `orientation` | Suggested orientation for the device when displaying the linked resource. | String | `landscape`, `portrait` or `auto` | `auto` | + +The `orientation` property is mostly relevant for resources with fixed dimensions (images, videos), where the orientation has an actual impact on how the resource is displayed. + +*In this example, all resources should be displayed in portrait mode.* + +```json +"metadata": { + "presentation": { + "orientation": "portrait" + } +} +``` +*In this example, a specific resource should be displayed in landscape mode.* + +```json +"readingOrder": [ + { + "href": "page1.html", + "type": "text/html", + "properties": { + "orientation": "landscape" + } + } +] +``` + +## Appendix A - JSON Schema + +The following JSON Schemas for this module are available under version control: + +- Metadata: +- Link Properties: + +For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resources: + +- +- \ No newline at end of file diff --git a/modules/transitions.md b/experimental/transitions.md similarity index 100% rename from modules/transitions.md rename to experimental/transitions.md diff --git a/modules/README.md b/modules/README.md index c96687e..4da6ca1 100644 --- a/modules/README.md +++ b/modules/README.md @@ -3,7 +3,6 @@ | Name | Description | | ----- | ------------ | | [Encryption](encryption.md) | Property which conveys to User Agents how a given resource has been encrypted. | -| [Presentation Hints](presentation.md) | Metadata and properties which convey to User Agents how a given publication should be presented. | ## Registering a module diff --git a/modules/presentation.md b/modules/presentation.md deleted file mode 100644 index 40122d6..0000000 --- a/modules/presentation.md +++ /dev/null @@ -1,269 +0,0 @@ -# Presentation Hints - -The Presentation Hints extension defines a number of hints for User Agents about the way content should be presented to the user. - -## 1. Presentation Hints in `metadata` - -In order to provide publication-wide Presentation Hints, this extension introduces a new element in the `metadata` object of [the Readium Web Publication Manifest](https://readium.org/webpub-manifest): - -| Key | Semantics | Type | -| ----- | --------- | -------- | -| `presentation` | Publication-wide presentation hints. | Object | - -The following elements may be included in `presentation`: - -- [`clipped`](#clipped) -- [`continuous`](#continuous) -- [`fit`](#fit) -- [`orientation`](#orientation) -- [`overflow`](#overflow) -- [`spread`](#spread) - -## 2. Presentation Hints as Link Properties - -In addition to publication-wide hints, this extension defines a number of Link Properties to provide resource-level hints in `readingOrder` or `resources`. - -The following elements may be included in `properties`: - -- [`clipped`](#clipped) -- [`fit`](#fit) -- [`orientation`](#orientation) -- [`page`](#page) -- [`spread`](#spread) - -## 3. Properties - -### clipped - -The `clipped` property is meant to adapt visual resources to any given viewport ratio. The clipped areas must not contain information which are mandatory for the comprehension of the resource. - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `clipped` | Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped. | Boolean | `true` or `false` | `false` | - -*In this example, resources are handled in a discontinuous way and each resource is scaled to fit the viewport height and clipped to fit different viewport widths. It behaves like turbomedia.* - -```json -"metadata": { - "readingProgression": "ttb", - "presentation": { - "continuous": false, - "fit": "height", - "clipped": true - - } -} -``` - -*In this example, a specific resource is scaled to fit the viewport width and clipped to fit different viewport heights.* - -```json -"readingOrder": [ - { - "href": "image1.webp", - "type": "image/webp", - "properties": { - "fit": "width", - "clipped": true - } - } -] -``` - -### continuous - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `continuous` | Indicates if consecutive linked resources from the `readingOrder` should be handled in a continuous or discontinuous way. | Boolean | `true` or `false` | `true` | - -*In this example, the user will not experience discontinuities between the different resources* - -```json -"metadata": { - "presentation": { - "continuous": true - } -} -``` - -### fit - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `fit` | Specifies constraints for the presentation of a linked resource within the viewport. | String | `contain`, `cover`, `width` or `height` | `contain` | - -| Value | Definition | -| ------- | ---------- | -| `contain` | The content is centered and scaled to fit both dimensions into the viewport. | -| `cover` | The content is centered and scaled to fill the viewport. | -| `width` | The content is centered and scaled to fit the viewport width. | -| `height` | The content is centered and scaled to fit the viewport height. | - -*In this example, resources are handled in a continuous way, the content is scrollable on the vertical axis and each resource fits the viewport width. It behaves like a webtoon.* - -```json -"metadata": { - "readingProgression": "ttb", - "presentation": { - "continuous": true, - "overflow": "scrolled", - "fit": "width" - } -} -``` -*In this example, a specific resource is scaled to fit the viewport.* - -```json -"readingOrder": [ - { - "href": "image1.webp", - "type": "image/webp", - "properties": { - "fit": "contain" - } - } -] -``` - -### orientation - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `orientation` | Suggested orientation for the device when displaying the linked resource. | String | `landscape`, `portrait` or `auto` | `auto` | - -The `orientation` property is mostly relevant for resources with fixed dimensions (images, videos), where the orientation has an actual impact on how the resource is displayed. - -*In this example, each resource should be displayed in portrait mode.* - -```json -"metadata": { - "presentation": { - "orientation": "portrait" - } -} -``` -*In this example, a specific resource should be displayed in landscape mode.* - -```json -"readingOrder": [ - { - "href": "page1.html", - "type": "text/html", - "properties": { - "orientation": "landscape" - } - } -] -``` - -### overflow - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `overflow` | Indicates if the overflow of linked resources from the `readingOrder` or `resources` should be handled using dynamic pagination or scrolling. | String | `paginated`, `scrolled` or `auto` | `auto` | - - -| Value | Definition | -| ------- | ---------- | -| `paginated` | Content overflow should be handled using dynamic pagination. | -| `scrolled` | Content overflow should be handled using scrolling. | -| `auto` | The User Agent can decide how overflow should be handled. | - -*Here is an example of a paginated mode requested by the author* - -```json -"metadata": { - "readingProgression": "ltr", - "presentation": { - "continuous": true, - "overflow": "paginated" - } -} -``` - -### page - -The `page` property is meant to provide a hint to Use Agents that rely on synthetic spreads to display more than a single resource at once. - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `page` | Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads. | String | `left`, `right` or `center` | None | - -*In this example, the first page should be displayed of the left of a synthetic spread, the second page on the right.* - -```json -"readingOrder": [ - { - "href": "page1.jpg", - "type": "image/jpeg", - "properties": { - "page": "left" - } - }, - { - "href": "page2.jpg", - "type": "image/jpeg", - "properties": { - "page": "right" - } - } -] -``` - -### spread - -| Key | Semantics | Type | Values | Default | -| ----- | --------- | -------- | --------- | ------- | -| `spread` | Indicates the condition to be met for the linked resource to be rendered within a synthetic spread. | String | `landscape`, `both`, `none` or `auto` | `auto` | - -| Value | Definition | -| ------- | ---------- | -| `landscape` | The resource should be displayed in a spread only if the device is in landscape mode. | -| `both` | The resource should be displayed in a spread whatever the device orientation is. | -| `none` | The resource should never be displayed in a spread. | -| `auto` | The resource is left to the User Agent. | - -*In this example, content should be displayed in a spread only if the device is in landscape mode.* - -```json -"metadata": { - "presentation": { - "spread": "landscape", - "fit": "contain" - } -} -``` -*In this example, content of these two pages should be displayed in a spread, one on the left, the other on the right, whatever the device orientation is.* - -```json -"readingOrder": [ - { - "href": "page1.jpg", - "type": "image/jpeg", - "properties": { - "spread": "both", - "page": "left" - } - }, - { - "href": "page2.jpg", - "type": "image/jpeg", - "properties": { - "spread": "both", - "page": "right" - } - } -] -``` - -## Appendix A - JSON Schema - -The following JSON Schemas for this module are available under version control: - -- Metadata: -- Link Properties: - -For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resources: - -- -- \ No newline at end of file diff --git a/profiles/divina.md b/profiles/divina.md index ffefbfa..a633913 100644 --- a/profiles/divina.md +++ b/profiles/divina.md @@ -15,7 +15,6 @@ ```json { "@context": "http://readium.org/webpub-manifest/context.jsonld", - "metadata": { "title": "Objectif Lune", "identifier": "urn:isbn:9782203001152", @@ -26,7 +25,6 @@ "published": "1953-12-30", "modified": "2018-12-10T18:21:18Z", "numberOfPages": 62, - "readingProgression": "ltr", "belongsTo": { "series": { "name": "Les Aventures de Tintin", @@ -34,11 +32,13 @@ } } }, - "links": [ - {"rel": "self", "href": "http://example.org/manifest.json", "type": "application/divina+json"} + { + "rel": "self", + "href": "http://example.org/manifest.json", + "type": "application/divina+json" + } ], - "readingOrder": [ { "rel": "cover", @@ -62,16 +62,16 @@ ## Introduction -The goal of this specification is to provide a profile dedicated to visual narratives for the [Readium Web Publication Manifest](https://readium.org/webpub-manifest). +The goal of this specification is to provide a profile dedicated to digital visual narratives (Divina) for the [Readium Web Publication Manifest](https://readium.org/webpub-manifest). -This profile relies on: +## 1. Declaring conformance to the Divina profile -* the use of [presentation hints](../modules/presentation.md) for specifying display constraints, -* the definition of a new collection type for implementing [guided navigation](#4-guided-navigation), -* the [transitions module](../modules/transitions.md) to manage transitions between resources of the reading order. +In order to declare that it conforms to the Divina Profile, a Readium Web Publication Manifest must: -While the Digital Visual Narrative Manifest is technically a profile of the Readium Web Publication Manifest, it has its own media type in order to maximize compatibilty with dedicated apps: `application/divina+json`. +- include a `conformsTo` property in its `metadata` section, with `https://readium.org/webpub-manifest/profiles/divina` as one of its values +- use `application/divina+json` as its media type +While the Divina Manifest is technically a profile of the Readium Web Publication Manifest, the use of its dedicated media type is recommended to maximize compatibility with applications that may target comics/manga specifically. ## 2. Listing Resources @@ -81,7 +81,7 @@ In addition to the normal requirements of a `readingOrder`, all Link Objects hav - they must point strictly to bitmap images -In addition, all Link Objects should include `width` and `height` to indicate the dimensions of each resource. +In addition, all Link Objects should also include `width` and `height` to indicate the dimensions of each resource. ## 3. Alternate Resources @@ -93,7 +93,7 @@ All Link Objects present in the `alternate` array: - should indicate their dimensions using `height` and `width` - may target a different language using `language` -*Example 1: A resource available in JPEG and WebP* +*Example 1: A resource available in JPEG and AVIF* ```json { @@ -101,8 +101,8 @@ All Link Objects present in the `alternate` array: "type": "image/jpeg", "alternate": [ { - "href": "http://example.org/page1.webp", - "type": "image/webp" + "href": "http://example.org/page1.avif", + "type": "image/avif" } ] } @@ -144,75 +144,92 @@ All Link Objects present in the `alternate` array: } ``` -## 4. Guided Navigation +## 4. Layout + +### 4.1. Fixed layout + +By default, each publication that conforms to the Divina profile is handled like a fixed layout publications, which means that: -In addition to having [a table of contents](https://readium.org/webpub-manifest/#6-table-of-contents), a visual narrative may also provide guided navigation where each reference is either: +- the publication is paginated by default, where each page is an image from the `readingOrder` +- images are usually displayed with both dimensions fully contained in the viewport by default +- reading systems can decide to display two images side by side in a spread, using the [`page`](../properties.md#page) property as a hint -- pointing directly to a resource (`image1.jpg`) -- or to a fragment of a resource using [Media Fragments](https://www.w3.org/TR/media-frags) (`image1.jpg#xywh=160,120,320,240`) +Reading systems are strongly encouraged to let the user decide if they prefer reading the publication: -This document introduces a new collection role to fulfill that goal: +- paginated or scrolled +- with or without spreads (for example, with spreads in landscape mode but without spreads in portrait mode) -| Role | Definition | Compact Collection? | Required? | -| ----- | ---------- | ------------------- | --------- | -| `guided` | Identifies a collection containing guided navigation into a publication. | Yes | No | +### 4.2. Scrolled publications -To avoid duplicating content between `readingOrder` and `guided`, Link Objects referenced in `guided` must only contain `href` and `title`. +For publications where a single continuous scroll is required to properly display the publication (such as webtoons for example), content creators should use the [`layout`](../contexts/default/README.md#layout-and-reading-progression) property with the `scrolled` value. -This current draft does not cover guided navigation over alternate versions of each image resource. +In order to override the default behaviour of displaying all images from the `readingOrder` in a single continuous scroll, this profile also introduces a new property for Link Objects: -*Example 4: Guided navigation with full page displayed before panels* +
+
break-scroll-before
+
Specifies that an item in the reading order should break the current continuous scroll and start a new one.
+
+ +*Example 4: A scrolled publication with a break in its continuous scroll* ```json -"guided": [ - { - "href": "http://example.org/page1.jpeg", - "title": "Page 1" - }, - { - "href": "http://example.org/page1.jpeg#xywh=0,0,300,200", - "title": "Panel 1" +{ + "metadata": { + "title": "The Cat Collector", + "identifier": "https://example.com/cat-collector", + "conformsTo": "https://readium.org/webpub-manifest/profiles/divina", + "layout": "scrolled" }, - { - "href": "http://example.org/page1.jpeg#xywh=300,200,310,200", - "title": "Panel 2" - } -] + "readingOrder": [ + { + "href": "episode1-image1.jpg", + "type": "image/jpeg" + }, + { + "href": "episode1-image2.jpg", + "type": "image/jpeg" + }, + { + "href": "episode1-image3.jpg", + "type": "image/jpeg" + }, + { + "href": "episode2-image1.jpg", + "type": "image/jpeg", + "properties": { + "break-scroll-before": true + } + }, + { + "href": "episode2-image2.jpg", + "type": "image/jpeg" + }, + { + "href": "episode2-image3.jpg", + "type": "image/jpeg" + } + ] +} ``` ## 5. Packaging -A Divina publication may be distributed unpackaged on the Web, but it may also be packaged for easy distribution as a single file. To achieve this goal, this specification defines the [Readium Packaging Format (RPF)](../packaging.md). +A Divina publication may be distributed unpackaged on the Web, but it may also be packaged for easy distribution as a single file. To achieve this goal, this specification relies on the [Readium Packaging Format](./packaging.md). To maximize compatibility with dedicated apps, such a package has its own file extension and media-type: - its file extension must be `.divina` - its media type must be `application/divina+zip` -As an alternative, the manifest may also be included into an EPUB 3 publication, an hybrid solution also specified in the [Readium Packaging Format (RPF)](../packaging.md) specification. This approach allows a publisher to create EPUB 3 fixed layout comics which are enriched by transitions, guided navigation, sounds etc. accessible via Divina compliant applications. - - -## Appendix A. Compliance Levels - -### Level 0 +As an alternative, the manifest may also be included in: -* Support for the [Readium Web Publication Manifest](https://readium.org/webpub-manifest) with bitmap images in `readingOrder` -* Support for [presentation hints](../modules/presentation.md) -* Support for [alternate resources](#3-alternate-resources) +- an EPUB 3 publication, as specified in the [Readium Packaging Format](./packaging.md#6-hybrid-epub-3--rpf-packages) specification +- or dedicated formats for comics such as CBZ/CBR -### Level 1 +## Appendix A. Examples -* Support for [guided navigation](#4-guided-navigation) -* Support for [transitions](../modules/transitions.md) - -### Level 2 - -* TBD - -## Appendix B. Examples - -*Example 5: A manga is a DiViNa where images are presented sequentially from right-to-left with a discontinuity between images that are not in the same spread* +*Example 5: A manga is a Divina where the reading progression is right-to-left* ```json @@ -221,11 +238,7 @@ As an alternative, the manifest may also be included into an EPUB 3 publication, "title": "Manga", "identifier": "https://example.com/manga", "conformsTo": "https://readium.org/webpub-manifest/profiles/divina", - "readingProgression": "rtl", - "presentation": { - "fit": "contain", - "spread": "landscape" - } + "readingProgression": "rtl" }, "readingOrder": [ { @@ -248,7 +261,7 @@ As an alternative, the manifest may also be included into an EPUB 3 publication, } ``` -*Example 6: A webtoon is a DiViNa where images are scrolled in a single continuous strip of content* +*Example 6: A continuously scrolled publication (a "webtoon") is a Divina where images are displayed in a single continuous strip of content* ```json @@ -257,12 +270,7 @@ As an alternative, the manifest may also be included into an EPUB 3 publication, "title": "Webtoon", "identifier": "https://example.com/webtoon", "conformsTo": "https://readium.org/webpub-manifest/profiles/divina", - "readingProgression": "ttb", - "presentation": { - "overflow": "scrolled", - "fit": "width", - "continuous": true - } + "layout": "scrolled" }, "readingOrder": [ { @@ -280,3 +288,13 @@ As an alternative, the manifest may also be included into an EPUB 3 publication, ] } ``` + +## Appendix B. JSON Schema + +The following JSON Schemas for this profile is available under version control: + +- Link Properties: + +For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resource: + +- \ No newline at end of file diff --git a/profiles/epub.md b/profiles/epub.md index e99ebe1..570910b 100644 --- a/profiles/epub.md +++ b/profiles/epub.md @@ -15,12 +15,6 @@ While EPUB publications can mostly be converted directly to the Readium Web Publ This profile is meant to facilitate backward compatibility with EPUB and ensure that these specialized elements are not lost when converting to the Readium Web Publication Manifest. -This profile relies on: - -* a declaration of [conformance](#1-declaring-conformance-with-the-epub-profile), -* some [restrictions on the resources of the readingOrder](#2-restrictions-on-the-resources-of-the readingorder), -* the definition of additional [collection roles](#3-collection-roles), [metadata elements](#4-metadata) and [link properties](#5-link-properties), -* the use of the [encryption module](../modules/encryption.md). ## 1. Declaring conformance with the EPUB Profile @@ -32,7 +26,15 @@ A Readium Web Publication Manifest that conforms to the EPUB Profile +- Collection roles: +- Link properties: + + +For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resources: + +- +- +- + +## Appendix B - Deprecated properties + +### `layout` in a `presentation` object + +This specification was initially responsible for documenting the layout of an entire publication using either: `reflowable` or `fixed`. + +This was handled using a `layout` property in a `presentation` object. + +```json +"metadata": { + "title": "Bella the dragon", + "presentation": { + "layout": "fixed" + } +} +``` + +This is no longer supported by this profile because `layout` became a first-class metadata defined in the default context. + +```json +"metadata": { + "title": "Bella the dragon", + "layout": "fixed" +} +``` + +### Orientation + +The EPUB specification allow content creators to specify the intended orientation of: + +- [an entire publication](https://www.w3.org/TR/epub-33/#orientation) +- [or a specific resource](https://www.w3.org/TR/epub-33/#orientation-overrides) + +This was originally supported in this EPUB profile through: + +- an `orientation` property for the `presentation` object in `metadata` (for the entire publication) +- and an `orientation` property in the `properties` of a Link Object (for a specific resource) + +This is no longer supported in Readium because forcing an orientation goes against the principles that we're trying to follow, where the user is always free to decide what feels best for them. + +### Spreads + +The EPUB specification allow content creators to specify when synthetic spreads should be presented to the user for a fixed layout document either for: + +- [an entire publication](https://www.w3.org/TR/epub-33/#spread) +- [or a specific resource](https://www.w3.org/TR/epub-33/#spread-overrides) + +This was originally supported in this EPUB profile through: + +- a `spread` property for the `presentation` object in `metadata` (for the entire publication) +- and a `spread` property in the `properties` of a Link Object (for a specific resource) + +This is no longer supported in Readium because forcing spreads goes against the principles that we're trying to follow, where the user is always free to decide what feels best for them. \ No newline at end of file diff --git a/properties.md b/properties.md index 4e136d3..0725902 100644 --- a/properties.md +++ b/properties.md @@ -4,16 +4,46 @@ Each Link Object may contain a Properties Object, containing a number of relevan This document is meant to provide an exhaustive list of properties that can be associated to a Link Object, along with their semantics and usage. + +## Core properties + +| Key | Semantics | Type | Values | +| ----- | --------- | -------- | --------- | +| [`page`](#page) | Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads. | String | `left`, `right` or `center` | + +### page + +The `page` property is meant to provide a hint to reading systems that rely on synthetic spreads to display more than a single resource at once. + + +*In this example, the first page should be displayed of the left of a synthetic spread, the second page on the right.* + +```json +"readingOrder": [ + { + "href": "page1.jpg", + "type": "image/jpeg", + "properties": { + "page": "left" + } + }, + { + "href": "page2.jpg", + "type": "image/jpeg", + "properties": { + "page": "right" + } + } +] +``` + + ## Extensions | Key | Semantics | Type | Values | Reference | | ----- | --------- | -------- | --------- | --------- | -| [`contains`](/profiles/epub.md#contains) | Indentifies content contained in the linked resource, that cannot be strictly identified using a media type. | Array | `mathml`, `onix`, `remote-resources`, `js`, `svg` or `xmp` | [EPUB Profile](/profiles/epub.md#properties) | +| [`contains`](/profiles/epub.md#contains) | Indentifies content contained in the linked resource, that cannot be strictly identified using a media type. | Array | `mathml`, `onix`, `remote-resources`, `js`, `svg` or `xmp` | [EPUB Profile](/profiles/epub.md#properties) | | [`layout`](/profiles/epub.md#layout) | Hint about the nature of the layout for the linked resources. | String | `fixed` or `reflowable` | [EPUB Profile](/profiles/epub.md#properties) | -| [`orientation`](/modules/presentation.md#orientation) | Suggested orientation for the device when displaying the linked resource. | String | `auto`, `landscape` or `portrait` | [Presentation Hints](/modules/presentation.md) | -| [`overflow`](/modules/presentation.md#overflow) | Suggested method for handling overflow while displaying the linked resource. | String | `auto`, `clipped`, `paginated` or `scrolled` | [Presentation Hints](/modules/presentation.md) | -| [`page`](/modules/presentation.md#page) | Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads. | String | `left`, `right` or `center` | [Presentation Hints](/modules/presentation.md) | -| [`spread`](/modules/presentation.md#spread) | Indicates the condition to be met for the linked resource to be rendered within a synthetic spread. | String | `auto`, `both`, `none` or `landscape` | [Presentation Hints](/modules/epub.md#properties) | | [`encrypted`](/modules/encryption.md) | Indicates how a given resource has been encrypted or obfuscated. | [Encryption Object](/modules/encryption.md#encryption-object) | See the definition of the Encryption Object | [Encryption Module](/modules/encryption.md) | ## OPDS 2.0 diff --git a/roles.md b/roles.md index 00a1aca..8c01ec8 100644 --- a/roles.md +++ b/roles.md @@ -14,13 +14,12 @@ The Readium Web Publication Manifest specification defines the following roles f | Role | Definition | Compact Collection? | Required? | Reference | | ----- | ---------- | ------------------- | --------- | --------- | -| `guided` | Identifies a collection containing guided navigation into a publication. | Yes | No | [Visual Narrative Profile](profiles/visual-narrative.md#4-guided-navigation) | -| `landmarks` | Identifies the collection that contains a list of points of interest. | Yes | No | [EPUB Profile](profiles/epub.md#collection-roles) | -| `loa` | Identifies the collection that contains a list of audio resources. | Yes | No | [EPUB Profile](profiles/epub.md#collection-roles) | -| `loi` | Identifies the collection that contains a list of illustrations. | Yes | No | [EPUB Profile](profiles/epub.md#collection-roles) | -| `lot` | Identifies the collection that contains a list of tables. | Yes | No | [EPUB Profile](profiles/epub.md#collection-roles) | -| `lov` | Identifies the collection that contains a list of videos. | Yes | No | [EPUB Profile](profiles/epub.md#collection-roles) | -| `pageList` | Identifies the collection that contains a list of pages. | Yes | No | [EPUB Profile](profiles/epub.md#collection-roles) | +| `landmarks` | Identifies the collection that contains a list of points of interest. | Yes | No | [EPUB Profile](profiles/epub.md#4-collection-roles) | +| `loa` | Identifies the collection that contains a list of audio resources. | Yes | No | [EPUB Profile](profiles/epub.md#4-collection-roles) | +| `loi` | Identifies the collection that contains a list of illustrations. | Yes | No | [EPUB Profile](profiles/epub.md#4-collection-roles) | +| `lot` | Identifies the collection that contains a list of tables. | Yes | No | [EPUB Profile](profiles/epub.md#4-collection-roles) | +| `lov` | Identifies the collection that contains a list of videos. | Yes | No | [EPUB Profile](profiles/epub.md#4-collection-roles) | +| `pageList` | Identifies the collection that contains a list of pages. | Yes | No | [EPUB Profile](profiles/epub.md#4-collection-roles) | ## OPDS 2.0 diff --git a/schema/experimental/presentation/metadata.schema.json b/schema/experimental/presentation/metadata.schema.json new file mode 100644 index 0000000..c248a81 --- /dev/null +++ b/schema/experimental/presentation/metadata.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://readium.org/webpub-manifest/schema/experimental/presentation/metadata.schema.json", + "title": "Presentation Hints - Metadata", + "type": "object", + "properties": { + "presentation": { + "type": "object", + "properties": { + "clipped": { + "description": "Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped.", + "type": "boolean" + }, + "fit": { + "description": "Specifies constraints for the presentation of a linked resource within the viewport.", + "type": "string", + "enum": [ + "width", + "height", + "contain", + "cover" + ] + }, + "orientation": { + "description": "Suggested orientation for the device when displaying the linked resource.", + "type": "string", + "enum": [ + "auto", + "landscape", + "portrait" + ] + } + } + } + } +} diff --git a/schema/extensions/presentation/properties.schema.json b/schema/experimental/presentation/properties.schema.json similarity index 56% rename from schema/extensions/presentation/properties.schema.json rename to schema/experimental/presentation/properties.schema.json index 9e0d681..5741fdf 100644 --- a/schema/extensions/presentation/properties.schema.json +++ b/schema/experimental/presentation/properties.schema.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://readium.org/webpub-manifest/schema/extensions/presentation/properties.schema.json", + "$id": "https://readium.org/webpub-manifest/schema/experimental/presentation/properties.schema.json", "title": "Presentation Hints - Link Properties", "type": "object", "properties": { @@ -26,25 +26,6 @@ "landscape", "portrait" ] - }, - "page": { - "description": "Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads.", - "type": "string", - "enum": [ - "left", - "right", - "center" - ] - }, - "spread": { - "description": "Indicates the condition to be met for the linked resource to be rendered within a synthetic spread.", - "type": "string", - "enum": [ - "auto", - "both", - "none", - "landscape" - ] } } } diff --git a/schema/extensions/divina/properties.schema.json b/schema/extensions/divina/properties.schema.json new file mode 100644 index 0000000..da4c9c9 --- /dev/null +++ b/schema/extensions/divina/properties.schema.json @@ -0,0 +1,13 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://readium.org/webpub-manifest/schema/extensions/divina/properties.schema.json", + "title": "Divina Profile - Link Properties", + "type": "object", + "properties": { + "break-scroll-before": { + "description": "Specifies that an item in the reading order should break the current continuous scroll and start a new one.", + "type": "boolean", + "default": false + } + } +} diff --git a/schema/extensions/encryption/properties.schema.json b/schema/extensions/encryption/properties.schema.json new file mode 100644 index 0000000..cb5f55a --- /dev/null +++ b/schema/extensions/encryption/properties.schema.json @@ -0,0 +1,40 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://readium.org/webpub-manifest/schema/extensions/encryption/properties.schema.json", + "title": "Encryption Module - Link Properties", + "type": "object", + "properties": { + "encrypted": { + "description": "Indicates that a resource is encrypted/obfuscated and provides relevant information for decryption", + "type": "object", + "properties": { + "algorithm": { + "description": "Identifies the algorithm used to encrypt the resource", + "type": "string", + "format": "uri" + }, + "compression": { + "description": "Compression method used on the resource", + "type": "string" + }, + "originalLength": { + "description": "Original length of the resource in bytes before compression and/or encryption", + "type": "integer" + }, + "profile": { + "description": "Identifies the encryption profile used to encrypt the resource", + "type": "string", + "format": "uri" + }, + "scheme": { + "description": "Identifies the encryption scheme used to encrypt the resource", + "type": "string", + "format": "uri" + } + }, + "required": [ + "algorithm" + ] + } + } +} diff --git a/schema/extensions/epub/metadata.schema.json b/schema/extensions/epub/metadata.schema.json index a9d9b84..cb49e57 100644 --- a/schema/extensions/epub/metadata.schema.json +++ b/schema/extensions/epub/metadata.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://readium.org/webpub-manifest/schema/extensions/epub/metadata.schema.json", - "title": "EPUB Extension - Metadata", + "title": "EPUB Profile - Metadata", "type": "object", "properties": { "mediaOverlay": { @@ -16,19 +16,6 @@ "type": "string" } } - }, - "presentation": { - "type": "object", - "properties": { - "layout": { - "description": "Hints how the layout of the resource should be presented", - "type": "string", - "enum": [ - "fixed", - "reflowable" - ] - } - } } } } diff --git a/schema/extensions/epub/properties.schema.json b/schema/extensions/epub/properties.schema.json index a0bdfa5..4d23ac2 100644 --- a/schema/extensions/epub/properties.schema.json +++ b/schema/extensions/epub/properties.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://readium.org/webpub-manifest/schema/extensions/epub/properties.schema.json", - "title": "EPUB Extension - Link Properties", + "title": "EPUB Profile - Link Properties", "type": "object", "properties": { "contains": { @@ -21,44 +21,12 @@ "uniqueItems": true }, "layout": { - "description": "Hints how the layout of the resource should be presented", + "description": "Hints how the layout of a specific resource should be presented", "type": "string", "enum": [ "fixed", "reflowable" ] - }, - "encrypted": { - "description": "Indicates that a resource is encrypted/obfuscated and provides relevant information for decryption", - "type": "object", - "properties": { - "algorithm": { - "description": "Identifies the algorithm used to encrypt the resource", - "type": "string", - "format": "uri" - }, - "compression": { - "description": "Compression method used on the resource", - "type": "string" - }, - "originalLength": { - "description": "Original length of the resource in bytes before compression and/or encryption", - "type": "integer" - }, - "profile": { - "description": "Identifies the encryption profile used to encrypt the resource", - "type": "string", - "format": "uri" - }, - "scheme": { - "description": "Identifies the encryption scheme used to encrypt the resource", - "type": "string", - "format": "uri" - } - }, - "required": [ - "algorithm" - ] } } } diff --git a/schema/extensions/presentation/metadata.schema.json b/schema/extensions/presentation/metadata.schema.json deleted file mode 100644 index 233c98b..0000000 --- a/schema/extensions/presentation/metadata.schema.json +++ /dev/null @@ -1,60 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://readium.org/webpub-manifest/schema/extensions/presentation/metadata.schema.json", - "title": "Presentation Hints - Metadata", - "type": "object", - "properties": { - "presentation": { - "type": "object", - "properties": { - "clipped": { - "description": "Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped.", - "type": "boolean" - }, - "continuous": { - "description": "Indicates if consecutive linked resources from the `reading order` should be handled in a continuous or discontinuous way.", - "type": "boolean" - }, - "fit": { - "description": "Specifies constraints for the presentation of a linked resource within the viewport.", - "type": "string", - "enum": [ - "width", - "height", - "contain", - "cover" - ] - }, - "orientation": { - "description": "Suggested orientation for the device when displaying the linked resource.", - "type": "string", - "enum": [ - "auto", - "landscape", - "portrait" - ] - }, - "overflow": { - "description": "Indicates if the overflow of linked resources from the `readingOrder` or `resources` should be handled using dynamic pagination or scrolling.", - "type": "string", - "enum": [ - "auto", - "paginated", - "scrolled", - "scrolled-continuous" - ] - }, - "spread": { - "description": "Indicates the condition to be met for the linked resource to be rendered within a synthetic spread.", - "type": "string", - "enum": [ - "auto", - "both", - "none", - "landscape" - ] - } - } - } - } -} diff --git a/schema/link.schema.json b/schema/link.schema.json index a862b6f..9804539 100644 --- a/schema/link.schema.json +++ b/schema/link.schema.json @@ -32,10 +32,24 @@ }, "properties": { "description": "Properties associated to the linked resource", + "type": "object", + "properties": { + "page": { + "description": "Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads.", + "type": "string", + "enum": [ + "left", + "right", + "center" + ] + } + }, "allOf": [ - { "$ref": "https://drafts.opds.io/schema/properties.schema.json" }, { "$ref": "extensions/epub/properties.schema.json" }, - { "$ref": "extensions/presentation/properties.schema.json" } + { "$ref": "extensions/encryption/properties.schema.json" }, + { "$ref": "extensions/divina/properties.schema.json" }, + { "$ref": "experimental/presentation/properties.schema.json" }, + { "$ref": "https://drafts.opds.io/schema/properties.schema.json" } ] }, "height": { diff --git a/schema/metadata.schema.json b/schema/metadata.schema.json index f09110c..53f7aaf 100644 --- a/schema/metadata.schema.json +++ b/schema/metadata.schema.json @@ -104,16 +104,22 @@ "subject": { "$ref": "subject.schema.json" }, + "layout": { + "description": "Hints how the layout of the publication should be presented", + "type": "string", + "enum": [ + "fixed", + "reflowable", + "scrolled" + ] + }, "readingProgression": { "type": "string", "enum": [ "rtl", - "ltr", - "ttb", - "btt", - "auto" + "ltr" ], - "default": "auto" + "default": "ltr" }, "description": { "type": "string" @@ -146,7 +152,7 @@ "$ref": "extensions/epub/metadata.schema.json" }, { - "$ref": "extensions/presentation/metadata.schema.json" + "$ref": "experimental/presentation/metadata.schema.json" } ] } \ No newline at end of file