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" }
    }
  ]
}

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.

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

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
    }
  ]
}

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"
    }
  ]
}
]

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.