diff --git a/README.md b/README.md index 41b2ed9..1cff12a 100644 --- a/README.md +++ b/README.md @@ -20,54 +20,36 @@ This document defines a syntax for Guided Navigation Documents, serialized in JS * Panel by panel navigation in comics/manga to facilitate reading on smaller screens. * Providing a textual transcript and/or image descriptions for highly illustrated publications such as [Divina](https://readium.org/webpub-manifest/profiles/divina). -## 1. Guided Navigation Documents +## 1. Guided Navigation Document -Guided Navigation Documents must be identified using the following media type: `application/guided-navigation+json`. +A Guided Navigation Document must be identified using the following media type: `application/guided-navigation+json`. -### 1.1. Top-level properties +### 1.1. `guided` property | Name | Description | Format | Required? | | ---- | ----------- | ------ | ---------- | -| `links` | References to other resources that are related to the current Guided Navigation Document. | An array of [Link Objects](https://readium.org/webpub-manifest/#24-the-link-object) | No | | `guided` | A sequence of resources and/or media fragments into these resources, meant to be presented sequentially to the user. | An array of [Guided Navigation Objects](#12-guided-navigation-object) | Yes | -*Example 1: A link to a subsequent Guided Navigation Document* - -```json -{ - "links": [ - { - "rel": "next", - "href": "guided-chapter2.json" - } - ], - "guided": [ - { - "textref": "chapter1.html", - "role": ["chapter"] - } - ] -} -``` ### 1.2. Guided Navigation Object Each Guided Navigation Object must either contain: - a `children` object containg at least one Guided Navigation Object -- or one or more of the following properties: `audioref`, `imgref` or `textref` +- or one or more of the following properties: `audioref`, `imgref` `text`, `textref` or `videoref` Guided Navigations Objects should include one or more values for `role`. | Name | Description | Format | | ---- | ----------- | ------ | -| `audioref` | References an audio resource or a fragment of it. | URI | -| `children` | Items that are children of the containing Guided Navigation Object. | Guided Navigation Objects | -| `imgref` | References an image or a fragment of it. | URI | | `role` | Convey the structural semantics of a publication | Array of [roles](#4-roles) | +| `audioref` | References an audio resource or a fragment of it. | URI reference | +| `imgref` | References an image or a fragment of it. | URI reference | | `text` | Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object. | String or Text Object | -| `textref` | References a textual resource or a fragment of it. | URI | +| `textref` | References a textual resource or a fragment of it. | URI reference | +| `videoref` | References a video resource or a fragment of it. | URI reference | +| `children` | Items that are children of the containing Guided Navigation Object. | Guided Navigation Objects | ## 2. Relationship to the Readium Web Publication Manifest @@ -89,43 +71,11 @@ Publications that conform to the [EPUB profile](https://readium.org/webpub-manif Users must be free to move in and out of a Guided Navigation experience at will. -To do so, publications should provide references to Guided Navigation Documents both at a publication-level and as an alternate to resources referenced in the `readingOrder`. - -#### 2.2.1 Publication-level - -All valid [Readium Web Publication Manifests](https://readium.org/webpub-manifest) must contain a `links` property with at least one reference to its canonical location. - -In order to indicate the presence of a Guided Navigation Document, `links` may also include an additional Link Object where: - -- `type` uses the dedicated value for Guided Navigation Documents: `application/guided-navigation+json` -- and the `rel` value simply indicates that the Guided Navigation Document is `related` to the publication - -Subsequent Guided Navigation Documents can be linked from this initial resource using the `links` property, in order to navigate throughout the publication. - -*Example 2: A publication links to a Guided Navigation Document* - -```json -"links": [ - { - "rel": "self", - "href": "https://example.com/manifest.json", - "type": "application/guided-navigation+json" - } - { - "rel": "related", - "href": "https://example.com/guided.json", - "type": "application/guided-navigation+json" - } -] -``` - -#### 2.2.2 Link-level - -In addition to a publication-level link, all resources in the `readingOrder` should also point to the Guided Navigation Document that references them using the `alternate` property. +To do so, all resources in the `readingOrder` must also point to the Guided Navigation Document that references them using the `alternate` property. If this Guided Navigation Document contains any `audioref` element, then the Link Object should also indicate the total duration for all `audioref` properties using `duration`. -*Example 3: An image in a Divina that links to a Guided Navigation Document as an alternative* +*Example 2: An image in a Divina that links to a Guided Navigation Document as an alternative* ```json "readingOrder": [ @@ -144,30 +94,20 @@ If this Guided Navigation Document contains any `audioref` element, then the Lin ## 3. Roles -> [!NOTE] -> There are a number of open issues that relate to roles: -> -> - Cherrypicking roles from EPUB 3 Structural Semantics Vocabulary 1.1: -> - Identifying skippable and escapable roles: -> - Defining a list of roles for Divina: - Roles are inherited from multiple specifications such as [HTML](https://html.spec.whatwg.org/), [ARIA](https://www.w3.org/TR/wai-aria-1.1/), [DPUB ARIA](https://www.w3.org/TR/dpub-aria-1.1/) and [EPUB 3 Semantics Vocabulary](https://www.w3.org/TR/epub-ssv-11/), in order to convey the structural semantics of a publication. The full list of supported roles is available at: Roles should be used by reading applications to implement skippability (based on user preferences, some items could be skipped) and escapability (allowing users to escape from the current context, for example escaping from the content of a table to go back to the main text). -## 4. Media References +## 4. Media Fragments > [!NOTE] -> The following media fragments have been identified as potential candidates for fragments in `audioref`, `imgref` and `textref`: +> The following media fragments have been identified as potential candidates for fragments in `audioref`, `imgref`, `textref` and `videoref`: > >**Audio**: > ->**Images:** -> -> - Rectangular regions: -> - Polygonal regions: +>**Images:** > >**Text:** > @@ -175,9 +115,7 @@ Roles should be used by reading applications to imp > - Text fragments: > > There are a number of open issues that relate to media fragments: -> -> - Support for non-rectangular regions: -> - Support for CSS selectors and positions in `textref`: + ## 5. Text @@ -188,7 +126,7 @@ Roles should be used by reading applications to imp | `ssml` | Contains an SSML representation of the text. | SSML | -*Example 4: Text representation with both plain text and SSML* +*Example 3: Text representation with both plain text and SSML* ```json { @@ -222,7 +160,7 @@ A few additional documents are available in order to illustrate how Guided Navig The following examples are also available to illustrate how other types of publication can be mapped to Guided Navigation: -*Example 5: Synchronizing text with pre-recorded audio* +*Example: Synchronizing text with pre-recorded audio* ```json { @@ -245,7 +183,7 @@ The following examples are also available to illustrate how other types of publi } ``` -*Example 6: Accessible audiobook using text fragments* +*Example: Accessible audiobook using text fragments* ```json { @@ -262,7 +200,7 @@ The following examples are also available to illustrate how other types of publi } ``` -*Example 7: Accessible audiobook using embedded text* +*Example: Accessible audiobook using embedded text* ```json { @@ -287,7 +225,7 @@ The following examples are also available to illustrate how other types of publi | ---- | ----------- | ------ | | `description` | Text, audio or image description for the current Guided Navigation Object. | Guided Navigation Object without `children` | -*Example 8: Audio and text description for an image* +*Example: Audio and text description for an image* ```json { @@ -323,7 +261,7 @@ The following examples are also available to illustrate how other types of publi | ---- | ----------- | ------ | | `multipleImages` | Two or more references to images or regions of different images. | Array of URI | -*Example 9: Two page spread that contains a panel across the entire spread* +*Example: Two page spread that contains a panel across the entire spread* ```json { @@ -351,7 +289,7 @@ The following examples are also available to illustrate how other types of publi | ---- | ----------- | ------ | | `character` | Identifies one or more character present in a given Guided Navigation object. | Array of strings | -*Example 10: Characters present in the panel of a comicbook* +*Example: Characters present in the panel of a comicbook* ```json { diff --git a/roles.md b/roles.md index 5c9e3e2..7aae73d 100644 --- a/roles.md +++ b/roles.md @@ -87,11 +87,18 @@ | Role | EPUB type equivalent | Definition | | ---- | -------------------- | ---------- | +| `bubble` | [`balloon`](https://www.w3.org/TR/epub-ssv-11/#sec-comics) | An area in a comic panel that contains the words, spoken or thought, of a character. | +| `foreword` | [`foreword`](https://www.w3.org/TR/epub-ssv-11/#sec-sections) | An introductory section that precedes the work, typically not written by the author of the work. | | `landmarks` | [`landmarks`](https://w3c.github.io/epub-specs/epub33/ssv/#sec-navigation) | A short summary of the principle ideas, concepts and conclusions of the work, or of a section or excerpt within it. | | `loa` | [`loa`](https://w3c.github.io/epub-specs/epub33/ssv/#sec-navigation) | A listing of audio clips included in the work. | | `loi` | [`loi`](https://w3c.github.io/epub-specs/epub33/ssv/#sec-navigation) | A listing of illustrations included in the work. | | `lot` | [`lot`](https://w3c.github.io/epub-specs/epub33/ssv/#sec-navigation) | A listing of tables included in the work. | | `lov` | [`lov`](https://w3c.github.io/epub-specs/epub33/ssv/#sec-navigation) | A listing of video clips included in the work. | +| `panel` | [`panel`](https://www.w3.org/TR/epub-ssv-11/#sec-comics) | An individual frame, or drawing. | +| `panelGroup` | [`panel-group`](https://www.w3.org/TR/epub-ssv-11/#sec-comics) | A group of panels (e.g., a strip). | +| `sound` | [`sound-area`](https://www.w3.org/TR/epub-ssv-11/#sec-comics) | An area of text in a comic panel that represents a sound. | +| `textRangeSmall` | [`text-range-small`](https://github.com/w3c/epub-specs/issues/2917) | | +| `textRangeLarge` | [`text-range-large`](https://github.com/w3c/epub-specs/issues/2917) | | ## List of skippable roles @@ -122,6 +129,10 @@ * `caption` * `list` * `listItem` +* `panelGroup` + * `panel` + * `bubble` + * `sound` * `table` * `columnheader` * `rowheader` diff --git a/schema/document.schema.json b/schema/document.schema.json index 55bcb92..beae66a 100644 --- a/schema/document.schema.json +++ b/schema/document.schema.json @@ -4,21 +4,81 @@ "title": "Readium Guided Navigation Document", "type": "object", "properties": { - "links": { - "type": "array", - "items": { - "$ref": "https://readium.org/webpub-manifest/schema/link.schema.json" - }, - }, "guided": { "type": "array", "items": { - "$ref": "object.schema.json" + "$ref": "#/$defs/object" }, "minItems": 1 } }, "required": [ "guided" - ] + ], + "$defs": { + "object": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "audioref": { + "type": "string", + "format": "uri-reference" + }, + "imgref": { + "type": "string", + "format": "uri-reference" + }, + "textref": { + "type": "string", + "format": "uri-reference" + }, + "videoref": { + "type": "string", + "format": "uri-reference" + }, + "text": { + "$ref": "text.schema.json" + }, + "role": { + "type": ["array"], + "items": { + "type": "string", + "$ref": "roles.schema.json" + } + }, + "children": { + "type": "array", + "items": { + "$ref": "object.schema.json" + }, + "minItems": 1 + }, + "description" : { + "$ref": "description.schema.json" + } + }, + "anyOf": [ + { + "required": ["audioref"] + }, + { + "required": ["imgref"] + }, + { + "required": ["textref"] + }, + { + "required": ["videoref"] + }, + { + "required": ["text"] + }, + { + "required": ["children"] + } + ] + } + } } \ No newline at end of file diff --git a/schema/object.schema.json b/schema/object.schema.json deleted file mode 100644 index ba47ba4..0000000 --- a/schema/object.schema.json +++ /dev/null @@ -1,67 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://readium.org/guided-navigation/schema/object.schema.json", - "title": "Readium Guided Navigation Object", - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "audioref": { - "type": "string", - "format": "uri-reference" - }, - "imgref": { - "type": "string", - "format": "uri-reference" - }, - "textref": { - "type": "string", - "format": "uri-reference" - }, - "videoref": { - "type": "string", - "format": "uri-reference" - }, - "text": { - "$ref": "text.schema.json" - }, - "role": { - "type": ["array"], - "items": { - "type": "string", - "$ref": "roles.schema.json" - } - }, - "children": { - "type": "array", - "items": { - "$ref": "object.schema.json" - }, - "minItems": 1 - }, - "description" : { - "$ref": "description.schema.json" - } - }, - "anyOf": [ - { - "required": ["audioref"] - }, - { - "required": ["imgref"] - }, - { - "required": ["textref"] - }, - { - "required": ["videoref"] - }, - { - "required": ["text"] - }, - { - "required": ["children"] - } - ] -} \ No newline at end of file diff --git a/schema/roles.schema.json b/schema/roles.schema.json index f14a2d5..d111000 100644 --- a/schema/roles.schema.json +++ b/schema/roles.schema.json @@ -15,6 +15,7 @@ "biblioref", "blockquote", "body", + "bubble", "caption", "chapter", "cell", @@ -62,6 +63,8 @@ "notice", "pagebreak", "pagelist", + "panel", + "panelGroup", "paragraph", "part", "preface", @@ -76,10 +79,13 @@ "section", "separator", "sequence", + "sound", "subtitle", "summary", "table", "term", + "textRangeSmall", + "textRangeLarge", "tip", "toc", "video"