{"id":13760760,"url":"https://github.com/readium/webpub-manifest","last_synced_at":"2025-06-27T08:38:19.751Z","repository":{"id":18429332,"uuid":"83317908","full_name":"readium/webpub-manifest","owner":"readium","description":"📜 A JSON based Web Publication Manifest format used at the core of the Readium project","archived":false,"fork":false,"pushed_at":"2025-04-03T22:45:54.000Z","size":2043,"stargazers_count":94,"open_issues_count":27,"forks_count":23,"subscribers_count":45,"default_branch":"master","last_synced_at":"2025-04-03T23:28:26.405Z","etag":null,"topics":["audiobooks","ebooks","epub","json","json-ld","manifest","publications","readium","specification","webpub"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/readium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-27T14:16:15.000Z","updated_at":"2025-04-03T22:45:57.000Z","dependencies_parsed_at":"2023-01-11T20:29:00.541Z","dependency_job_id":"130af1b0-3011-4d56-9b4b-84beea647b34","html_url":"https://github.com/readium/webpub-manifest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readium%2Fwebpub-manifest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readium%2Fwebpub-manifest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readium%2Fwebpub-manifest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readium%2Fwebpub-manifest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readium","download_url":"https://codeload.github.com/readium/webpub-manifest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253410646,"owners_count":21904129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audiobooks","ebooks","epub","json","json-ld","manifest","publications","readium","specification","webpub"],"created_at":"2024-08-03T13:01:20.605Z","updated_at":"2025-05-10T11:31:44.264Z","avatar_url":"https://github.com/readium.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"# Readium Web Publication Manifest\n\nThe Readium Web Publication Manifest is a JSON-based document meant to represent and distribute publications over HTTPS.\n\nIt is the primary exchange format used in the [Readium Architecture](https://readium.org/architecture) and serves as the main building block for [OPDS 2.0](https://drafts.opds.io/opds-2.0). \n\n**Editors:**\n\n* Hadrien Gardeur\n\n**Participate:**\n\n* [GitHub readium/webpub-manifest](https://github.com/readium/webpub-manifest)\n* [File an issue](https://github.com/readium/webpub-manifest/issues)\n\n## Table of Contents\n\n* [Example](#example)\n* [1. Introduction](#1-introduction)\n  + [1.1. Goals](#11-goals)\n  + [1.2. Terminology](#12-terminology)\n  + [1.3. Abstract Model](#13-abstract-model)\n* [2. Syntax](#2-syntax)\n  + [2.1. Sub-Collections](#21-sub-collections)\n  + [2.2. Metadata](#22-metadata)\n  + [2.3. Links](#23-links)\n  + [2.4. The Link Object](#24-the-link-object)\n* [3. Resources in the Reading Order](#3-resources-in-the-reading-order)\n* [4. Media Type](#4-media-type)\n* [5. Discovering a Manifest](#5-discovering-a-manifest)\n* [6. Table of Contents](#6-table-of-contents)\n* [7. Cover](#7-cover)\n* [8. Extensibility](#8-extensibility)\n* [9. Packaging a Readium Web Publication](#9-packaging)\n* [Appendix A. JSON Schema](#appendix-a-json-schema)\n\n## Example\n\n```json\n{\n  \"@context\": \"https://readium.org/webpub-manifest/context.jsonld\",\n  \n  \"metadata\": {\n    \"@type\": \"http://schema.org/Book\",\n    \"title\": \"Moby-Dick\",\n    \"author\": \"Herman Melville\",\n    \"identifier\": \"urn:isbn:978031600000X\",\n    \"language\": \"en\",\n    \"modified\": \"2015-09-29T17:00:00Z\"\n  },\n\n  \"links\": [\n    {\"rel\": \"self\", \"href\": \"https://example.com/manifest.json\", \"type\": \"application/webpub+json\"},\n    {\"rel\": \"alternate\", \"href\": \"https://example.com/publication.epub\", \"type\": \"application/epub+zip\"},\n    {\"rel\": \"search\", \"href\": \"https://example.com/search{?query}\", \"type\": \"text/html\", \"templated\": true}\n  ],\n  \n  \"readingOrder\": [\n    {\"href\": \"https://example.com/c001.html\", \"type\": \"text/html\", \"title\": \"Chapter 1\"}, \n    {\"href\": \"https://example.com/c002.html\", \"type\": \"text/html\", \"title\": \"Chapter 2\"}\n  ],\n\n  \"resources\": [\n    {\"rel\": \"cover\", \"href\": \"https://example.com/cover.jpg\", \"type\": \"image/jpeg\", \"height\": 600, \"width\": 400},\n    {\"href\": \"https://example.com/style.css\", \"type\": \"text/css\"}, \n    {\"href\": \"https://example.com/whale.jpg\", \"type\": \"image/jpeg\"}, \n    {\"href\": \"https://example.com/boat.svg\", \"type\": \"image/svg+xml\"}, \n    {\"href\": \"https://example.com/notes.html\", \"type\": \"text/html\"}\n  ]\n}\n```\n\n## 1. Introduction\n\n### 1.1. Goals\n\nWhile the Web is the largest collection of interlinked documents ever created, it lacks a mechanism for expressing how a collection of resources, when grouped together can represent a publication.\n\nPublication formats such as EPUB or CBZ/CBR group these documents together using a container format, making them easier to archive or transmit as a whole. But they also break an important promise of the Web: the resources of a publication are not available through HTTP to any client that would like to access them.\n\nW3C has recently provided a definition for a [Web Publication](https://w3c.github.io/dpub-pwp-ucr/):\n\n\u003e 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.\n\nIt also provides a definition for a manifest in the context of a Web Publication:\n\u003e [...] **manifest** refers to an abstract means to contain information necessary to the proper management, rendering, and so on, of a publication. \n\nThe Readium Web Publication Manifest is an attempt to standardize a JSON based manifest format that follows both definitions.\n\nTo facilitate the interoperability between EPUB and Web Publications, this document also defines a number of extension points to fully support EPUB specific features.\n\n### 1.2. Terminology\n\n\u003cdl\u003e\n \u003cdt id=\"collection\"\u003eCollection\u003c/dt\u003e\n \u003cdd\u003eA grouping of some variable number of data items. In the context of this specification, a collection is defined as a grouping of metadata, links and sub-collections.\u003c/dd\u003e\n \u003cdt\u003eFull Collection\u003c/dt\u003e\n \u003cdd\u003eA collection that contains at least two or more data items among metadata, links and sub-collections.\u003c/dd\u003e\n \u003cdt\u003eCompact Collection\u003c/dt\u003e\n \u003cdd\u003eA collection that contains one or more links, but doesn't contain any metadata or sub-collections.\u003c/dd\u003e\n \u003cdt\u003eManifest\u003c/dt\u003e\n \u003cdd\u003eA manifest is a full collection that represents structured information about a publication.\u003c/dd\u003e\n\u003c/dl\u003e\n\n### 1.3. Abstract Model\n\nThe Readium Web Publication Manifest is based on a hypermedia model inspired by [Atom](https://tools.ietf.org/html/rfc4287), [HAL](http://stateless.co/hal_specification.html), [Siren](https://github.com/kevinswiber/siren) and [Collection+JSON](http://amundsen.com/media-types/collection/format/) among others.\n\nEvery Readium Web Publication Manifest is a [collection](#collection) that \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e contain:\n\n- [metadata](#22-metadata)\n- [links](#23-links)\n- a [reading order](#21-sub-collections)\n\n\n## 2. Syntax\n\n### 2.1. Sub-Collections\n\nThis specification defines two collection roles that are the building blocks of any manifest:\n\n| Role  | Definition | Compact Collection? | Required? |\n| ----- | ---------- | ------------------- | --------- |\n| `readingOrder`  | Identifies a list of resources in reading order for the publication.  | Yes  | Yes  |\n| `resources`  | Identifies resources that are necessary for rendering the publication.  | Yes  | No  |\n\nBoth collections are compact collections, which means that they contain one or more [Link Objects](#24-the-link-object). \n\nAll additional collection roles are defined in the [Collection Roles registry](roles.md).\n\nExtensions that are not registered in the registry \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e use a URI for their role.\n\nA manifest \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e contain a `readingOrder` sub-collection.\n\nOther resources that are required to render the publication \u003cstrong class=\"rfc\"\u003eshould\u003c/strong\u003e be listed in `resources`.\n\nAll resources listed in `readingOrder` and `resources` \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e indicate their media type using `type`.\n\n*Example 1: Reading order and list of resources*\n\n```json\n{\n  \"readingOrder\": [\n    {\"href\": \"/chapter1\", \"type\": \"text/html\"},\n    {\"href\": \"/chapter2\", \"type\": \"text/html\"}\n  ],\n  \"resources\": [\n    {\"href\": \"/style.css\", \"type\": \"text/css\"},\n    {\"href\": \"/image1.jpg\", \"type\": \"image/jpeg\"}\n  ]\n}\n```\n\n\n\n### 2.2. Metadata\n\nJSON-LD provides an easy and standard way to extend existing JSON document: through the addition of a context, we can associate keys in a document to Linked Data elements from various vocabularies.\n\nThe Web Publication Manifest relies on JSON-LD to provide a context for the `metadata` object of the manifest.\n\nWhile JSON-LD is very flexible and allows the context to be defined in-line (local context) or referenced (URI), the Web Publication Manifest restricts context definition strictly to references (URIs) at the top-level of the document.\n\nThe Web Publication Manifest defines an initial registry of well-known context documents, which currently includes the following references:\n\n| Name  | URI | Description | Required? |\n| ---- | ----------- | ------------- | --------- |\n[Default Context](contexts/default/) | [https://readium.org/webpub-manifest/context.jsonld](https://readium.org/webpub-manifest/context.jsonld)  | Default context definition used in every Web Publication Manifest. | Yes |\n\nContext documents are all defined and listed in the [Context Documents registry](contexts/).\n\nThe Readium Web Publication Manifest has a single requirement in terms of metadata: all publications \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e include a [title](contexts/default/#title).\n\nIn addition all publications \u003cstrong class=\"rfc\"\u003eshould\u003c/strong\u003e include a `@type` key to describe the nature of the publication.\n\n*Example 2: Minimal metadata*\n\n```json\n\"metadata\": {\n  \"@type\": \"http://schema.org/Book\",\n  \"title\": \"Test Publication\"\n}\n```\n\n### 2.3. Links\n\nLinks are expressed using the `links` key that contains one or more [Link Objects](#24-the-link-object).\n\nA manifest \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e contain at least one link using the `self` relationship where `href` is an absolute URI to the canonical location of the manifest.\n\n*Example 3: Link to the canonical location of a manifest*\n\n```json\n\"links\": [\n  {\n    \"rel\": \"self\",\n    \"href\": \"http://example.org/manifest.json\",\n    \"type\": \"application/webpub+json\"\n  }\n]\n```\nA manifest \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e also contain other links, such as a `alternate` link to an EPUB 3.2 version of the publication for example.\n\nLink relations that are currently used in this specification and its extensions are listed in the [Link Relations registry](relationships.md).\n\n### 2.4. The Link Object\n\nThe Link Object is a core component of the Readium Web Publication Manifest JSON syntax.\n\nIt represents a link to a resource along with a set of metadata associated with that resource.\n\nThis specification defines the following keys for this JSON object:\n\n| Key  | Definition | Format | Required? |\n| ---- | -----------| -------| ----------|\n| `href`  | URI or URI template of the linked resource  | URI or URI template | Yes  |\n| `templated`  | Indicates that `href` is a URI template  | Boolean, defaults to `false`  | Only when `href` is a URI template  |\n| `type`  | Media type of the linked resource  | MIME Media Type  | No  |\n| `title`  | Title of the linked resource  | String  | No  |\n| `rel`  | Relation between the resource and its containing collection  | One or more [Link Relations](relationships.md) | No  |\n| `properties`  | Properties associated to the linked resource  | [Properties Object](properties.md)  | No |\n| `height`  | Height of the linked resource in pixels | Integer  | No  |\n| `width`  | Width of the linked resource in pixels | Integer | No  |\n| `size`  | Original size of the resource in bytes, prior to any use of encryption or compression in an archive | Integer | No  |\n| `duration`  | Duration of the linked resource in seconds | Float| No  |\n| `bitrate`  | Bit rate of the linked resource in kilobits per second | Float| No  |\n| `language`  | Expected language of the linked resource | One or more [BCP 47 Language Tag](https://tools.ietf.org/html/bcp47) | No  |\n| `alternate`  | Alternate resources for the linked resource | One or more [Link Objects](#24-the-link-object) | No |\n| `children`  | Resources that are children of the linked resource, in the context of a given collection role | One or more [Link Objects](#24-the-link-object) | No |\n\n## 3. Resources in the Reading Order\n\nThe `readingOrder` of a manifest \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e contain references to any text, image, video or audio resource that can be opened in a Web browser.\n\n## 4. Media Type\n\nThis specification introduces a dedicated media type value to identify the Readium Web Publication Manifest: `application/webpub+json`.\n\nAll HTTP responses for the manifest \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e indicate this media type in their headers.\n\n## 5. Discovering a Manifest\n\nThe Readium Web Publication Manifest \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e be referenced by resources included in its `readingOrder` or `resources` using a link.\n\nSuch links \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e include:\n\n- `application/webpub+json` as the media type of the manifest\n- `manifest` as the relation of the link\n\n*Example 4: Link in HTML to a manifest*\n\n```html\n\u003clink href=\"manifest.json\" rel=\"manifest\" type=\"application/webpub+json\"\u003e\n```\n\n*Example 5: Link in HTTP headers to a manifest*\n\n```\nLink: \u003chttp://example.org/manifest.json\u003e; rel=\"manifest\";\n         type=\"application/webpub+json\"\n```\n\n## 6. Table of Contents\n\nA Readium Web Publication Manifest \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e contain a reference to a table of contents.\n\nIn order to represent a table of contents in the manifest, this specification introduces an additional collection role:\n\n| Role  | Definition | Compact Collection? | Required? |\n| ----- | ---------- | ------------------- | --------- |\n| `toc`  | Identifies the collection that contains a table of contents. | Yes  | No  |\n\n*Example 6: Partial TOC for an audiobook*\n\n```json\n\"toc\": [\n  {\n    \"href\": \"track1.mp3#t=71\",\n    \"title\": \"Part 1 - This World\",\n    \"children\": [\n      {\n        \"href\": \"track1.mp3#t=80\",\n        \"title\": \"Section 1 - Of the Nature of Flatland\"\n      },\n      {\n        \"href\": \"track1.mp3#t=415\",\n        \"title\": \"Section 2 - Of the Climate and Houses in Flatland\"\n      },\n      {\n        \"href\": \"track1.mp3#t=789\",\n        \"title\": \"Section 3 - Concerning the Inhabitants of Flatland\"\n      }\n    ]\n  }\n]\n```\n\n\nAs a fallback mechanism, a Readium Web Publication Manifest \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e identify an HTML or XHTML resource in `readingOrder` or `resources` as a table of contents using the `contents` link relation.\n\n*Example 7: Reference to an HTML resource containing a TOC*\n\n```json\n{\n  \"rel\": \"contents\", \n  \"href\": \"contents.html\", \n  \"type\": \"text/html\"\n}\n```\n\nA User Agent \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e also rely on the `title` key included in each Link Object of the `readingOrder` to extract a minimal table of contents.\n\n[The EPUB profile](profiles/epub.md) also defines [additional collection roles](profiles/epub.md#collection-roles) for embedding navigation directly in the manifest.\n\n## 7. Cover\n\nA Readium Web Publication Manifest \u003cstrong class=\"rfc\"\u003emay\u003c/strong\u003e contain a reference to a cover.\n\nLink Objects in `readingOrder`, `resources` or `links` can be identified as such using the `cover` link relation.\n\nAll Link Objects containing the `cover` link relation \u003cstrong class=\"rfc\"\u003emust\u003c/strong\u003e reference an image directly. They \u003cstrong class=\"rfc\"\u003eshould\u003c/strong\u003e include a `height` and `width` to facilitate how they are processed by User Agents.\n\nThis specification recommends using one of the following media types: `image/jpeg`, `image/png`, `image/gif`, `image/avif` or `image/svg+xml`. \n\n*Example 8: Reference to a cover*\n\n```json\n{\n  \"rel\": \"cover\", \n  \"href\": \"cover.jpg\", \n  \"type\": \"image/jpeg\", \n  \"height\": 600, \n  \"width\": 400\n}\n```\n\n## 8. Extensibility\n\nThe manifest provides multiple extension points:\n\n- additional collection roles using the [registry of roles](roles.md) or URIs\n- additional metadata using schema.org, terms from the [registry of context documents](contexts/) or URIs (for individual terms)\n- additional link relations from the [IANA link registry](https://www.iana.org/assignments/link-relations/link-relations.xhtml) or URIs\n- additional properties using the [registry of properties](properties.md)\n\nIn addition to these extension points, this specification defines both a [profile registry](profiles/) and a [module registry](modules/) as well.\n\nThe initial registry, contains the following profiles:\n\n| Name  |  Description |\n| ----- | ------------ |\n| [Audiobook Profile](profiles/audiobook.md) |  A profile for Audiobooks. |\n| [Divina Profile](profiles/divina.md) | A profile for Digital Visual Narrative publications (comics, manga and bandes dessinées). |\n| [EPUB Profile](profiles/epub.md) | A profile for EPUB publications served as Web Publications. |\n| [PDF Profile](profiles/pdf.md) | A profile for PDF documents served as Web Publications. |\n\n## 9. Packaging\n\nA Readium Web 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).\n\n## Appendix A. JSON Schema\n\nA JSON Schema is available under version control at [https://github.com/readium/webpub-manifest/tree/master/schema](https://github.com/readium/webpub-manifest/tree/master/schema)\n\nFor the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resource: [https://readium.org/webpub-manifest/schema/publication.schema.json](https://readium.org/webpub-manifest/schema/publication.schema.json)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadium%2Fwebpub-manifest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadium%2Fwebpub-manifest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadium%2Fwebpub-manifest/lists"}