webpub-manifest

Readium Logo

Visual Narrative Profile

Example

{
  "@context": "http://readium.org/webpub-manifest/context.jsonld",
  
  "metadata": {
    "identifier": "urn:isbn:9782203001152",
    "title": "Objectif Lune",
    "author": "Hergé",
    "language": "fr",
    "publisher": "Casterman",
    "published": "1953-12-30",
    "modified": "2018-12-10T18:21:18Z",
    "numberOfPages": 62,
    "belongsTo": {
      "series": {
        "name": "Les Aventures de Tintin",
        "position": 16
      }
    }
  },

  "links": [
    {"rel": "self", "href": "http://example.org/manifest.json", "type": "application/visual-narrative+json"}
  ],

  "readingOrder": [
    {
      "rel": "cover",
      "href": "http://example.org/cover.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "center" }
    }, 
    {
      "href": "http://example.org/page1.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "right" }
    }, 
    {
      "href": "http://example.org/page2.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "left" }
    }, 
    {
      "href": "http://example.org/page3.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "right" }
    }
  ]
}

1. Introduction

The goal of this document is to provide a profile dedicated to visual narratives for the Readium Web Publication Manifest that will cover the following requirements:

While the 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/visual-narrative+json.

2. Listing Visual Narrative Resources

A visual narratived is divided into one or more images, which are all listed in the readingOrder of the manifest.

In addition to the normal requirements of a readingOrder, all Link Objects have the following additional requirements:

In addition, all Link Objects should include width and height to indicate the dimensions of each resource

3. Alternate Visual Resources

In order to provide multiple variants of the same resource, Link Objects in the readingOrder may rely on the alternate key.

All Link Objects present in the alternate array:

Example 1: A resource available in JPEG and WebP

{
  "href": "http://example.org/page1.jpeg", 
  "type": "image/jpeg", 
  "alternate": [
    {
      "href": "http://example.org/page1.webp", 
      "type": "image/webp"
    }
  ]
}

Example 2: A resource available in French and Japanese

{
  "href": "http://example.org/page1.jpeg", 
  "type": "image/jpeg",
  "hreflang": "fr"
  "alternate": [
    {
      "href": "http://example.org/page1-jp.jpeg", 
      "type": "image/jpeg",
      "hreflang": "jp"
    }
  ]
}

Example 3: A resource available in two different resolutions

{
  "href": "http://example.org/page1.jpeg", 
  "type": "image/jpeg",
  "width": 546,
  "height": 760,
  "alternate": [
    {
      "href": "http://example.org/page1-high.jpeg", 
      "type": "image/jpeg",
      "width": 1092,
      "height": 1520
    }
  ]
}

4. Guided Navigation

In addition to having a table of contents, a visual narrative may also provide guided navigation where each reference is either:

This document introduces a new collection role to fulfill that goal:

Role Definition Compact Collection? Required?
guided Identifies a collection containing guided navigation into a publication. Yes No

To avoid duplicating content between readingOrder and guided, Link Objects referenced in guided should only contain href, title and children.

This current draft does not cover guided navigation over alternate versions of each image resource.

Example 4: Guided navigation in a single page

"guided": [
{
  "href": "http://example.org/page1.jpeg",
  "title": "Page 1",
  "children": [
    {
      "href": "http://example.org/page1.jpeg#xywh=0,0,300,200",
      "title": "Panel 1"
    },
    {
      "href": "http://example.org/page1.jpeg#xywh=300,200,310,200",
      "title": "Panel 2"
    }
  ]
}
]

5. Package

In order to facilitate distribution, both manifest and images can also be distributed using a package based on the requirements expressed for the Readium Web Publication Manifest.

To maximize compatibility with comics apps, the package for this profile has its own file extension and media-type:

As an alternative, the manifest can also be added to a CBZ file at the same well-known location.

Appendix A. Webtoons

This section is non-normative.

Note: We’re currently missing the ability to indicate how an image should fit on the screen. The current default is to fit both dimensions on screen, which would not work well with webtoons. In this non-normative appendix, we’re currently using fit for this use case.

Webtoons are probably the most successful form of digital native visual narrative. Originally from South Korea, they’re now becoming popular in Japan and France as well and should be covered by this profile.

We could either consider that a webtoon is:

With the first approach, the readingOrder contains a single image:

"readingOrder": [
  {
    "href": "long-image.jpg",
    "type": "image/jpeg",
    "properties": {
      "fit": "width"
    }
  }
]

A second approach is based on using multiple images, which could be better for performance on large webtoons.

In this case, a webtoon becomes a list of images that should be presented in a continuous scroll (with no gap or margin between images):

"metadata": {
  "rendition": {
    "overflow": "scrolled-continuous",
    "fit": "width"
  }
},
"readingOrder": [
  {
    "href": "image1.jpg",
    "type": "image/jpeg"
  },
  {
    "href": "image2.jpg",
    "type": "image/jpeg"
  },
  {
    "href": "image3.jpg",
    "type": "image/jpeg"
  }
]