From d4beb9dd1a1a5c21618889381529f38a8cb502c1 Mon Sep 17 00:00:00 2001 From: Hadrien Gardeur Date: Thu, 19 Feb 2026 18:07:34 +0100 Subject: [PATCH 1/4] Added further roles from EPUB SSV --- roles.md | 5 +++++ schema/roles.schema.json | 4 ++++ 2 files changed, 9 insertions(+) diff --git a/roles.md b/roles.md index 5c9e3e2..52ca862 100644 --- a/roles.md +++ b/roles.md @@ -87,11 +87,16 @@ | 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` | [`soundArea`](https://www.w3.org/TR/epub-ssv-11/#sec-comics) | An area of text in a comic panel that represents a sound. | ## List of skippable roles diff --git a/schema/roles.schema.json b/schema/roles.schema.json index f14a2d5..e594ce5 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,6 +79,7 @@ "section", "separator", "sequence", + "sound", "subtitle", "summary", "table", From 978c50b83ef67f0fc307a43def5aff2401eeb3f1 Mon Sep 17 00:00:00 2001 From: Hadrien Gardeur Date: Fri, 20 Feb 2026 11:19:45 +0100 Subject: [PATCH 2/4] Reworked README and JSON Schema to drop publication-level GND --- README.md | 106 ++++++++---------------------------- schema/document.schema.json | 76 +++++++++++++++++++++++--- schema/object.schema.json | 67 ----------------------- 3 files changed, 90 insertions(+), 159 deletions(-) delete mode 100644 schema/object.schema.json 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/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 From 596baee0e20f334c15509ef8d9ffc36e1b8dcef2 Mon Sep 17 00:00:00 2001 From: Hadrien Gardeur Date: Fri, 20 Feb 2026 12:05:48 +0100 Subject: [PATCH 3/4] Added escapability for comic related roles --- roles.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/roles.md b/roles.md index 52ca862..fa4b2a1 100644 --- a/roles.md +++ b/roles.md @@ -96,7 +96,7 @@ | `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` | [`soundArea`](https://www.w3.org/TR/epub-ssv-11/#sec-comics) | An area of text in a comic panel that represents a sound. | +| `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. | ## List of skippable roles @@ -127,6 +127,10 @@ * `caption` * `list` * `listItem` +* `panelGroup` + * `panel` + * `bubble` + * `sound` * `table` * `columnheader` * `rowheader` From 20d908c49bb1427dd597eb15201ff2a24ee3038a Mon Sep 17 00:00:00 2001 From: Hadrien Gardeur Date: Tue, 3 Mar 2026 10:39:54 +0100 Subject: [PATCH 4/4] Added new roles votes by W3C cf https://github.com/w3c/epub-specs/issues/2917 --- roles.md | 2 ++ schema/roles.schema.json | 2 ++ 2 files changed, 4 insertions(+) diff --git a/roles.md b/roles.md index fa4b2a1..7aae73d 100644 --- a/roles.md +++ b/roles.md @@ -97,6 +97,8 @@ | `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 diff --git a/schema/roles.schema.json b/schema/roles.schema.json index e594ce5..d111000 100644 --- a/schema/roles.schema.json +++ b/schema/roles.schema.json @@ -84,6 +84,8 @@ "summary", "table", "term", + "textRangeSmall", + "textRangeLarge", "tip", "toc", "video"