This specification defines a file format and processing model for packaging into a single-file container the set of related resources and associated metadata that comprise a digital publication.

Introduction

A digital publication Package is used:

• To exchange in-progress packaged publications between different individuals and/or different organizations;

• To provide finalized packaged publications from a publisher or conversion house to different distribution or sales channels; and

• To deliver packaged publications to users or user agents.

This specification is based on proven technologies and allows digital publications to be packaged in an easy way, hence the term "lightweight" used in its name.

Terminology

This document uses terminology defined by the W3C Note "Publishing and Linking on the Web" [[publishing-linking]], including, in particular, user and user agent.

In addition, the following terminology is defined for use in this specification:

Codec content types

Content types that have intrinsic binary format qualities, such as video and audio media types which are already designed for optimum compression, or which provide optimized streaming capabilities.

Non-Codec content types

Content types that benefit from compression due to the nature of their internal data structure, such as file formats based on character strings (for example, HTML, CSS, etc.).

Package

Single-file container for the set of constituent resources and associated metadata that comprise a digital publication.

Primary Entry Page

Preferred starting resource for a digital publication, enabling in some cases the discovery of its Publication Manifest.

Digital Publication

Set of constituent resources and associated metadata, organized together in a uniquely identifiable grouping.

Publication Manifest

[[JSON-LD]] representation of a digital publication as defined in [[pub-manifest]].

Root Directory

Base directory of the Package file system.

Only the first instance of a term in a section is linked to its definition.

Packaging format

For packaging the set of constituent resources and associated metadata that comprise a digital publication, this specification uses the ZIP format as specified in ISO/IEC 21320-1:2015 ([[ISO21320]] and [[zip]]).

Compression of resources

When stored in a Package, resources with Non-Codec content types SHOULD be compressed and the Deflate compression algorithm MUST be used. This practice ensures that file entries stored in the Package have a smaller size.

Resources with Codec content types SHOULD be stored without compression. In such case, compression would introduce unnecessary processing overhead at production time (especially with large resource files) and would impact audio/video playback performance at consumption time.

File and Directory Structure

A Package MUST include at least one of the following files in its Root Directory:

• A file named publication.json, which MUST be in the format defined for Publication Manifests.
• A file named index.html which MUST follow the requirements of the Primary Entry Page of a digital publication.

The Root Directory is virtual in nature: a user agent might or might not generate a physical root directory for the contents of the Package if such contents are unpackaged.

The contents of both files MUST not be encrypted.

A Package MUST also include all resources within the bounds of the digital publication, i.e. the finite set of resources obtained from the union of resources listed in the default reading order and resource list of the Publication Manifest.

These resource files MAY be in any location descendant from the Root Directory, or in the Root Directory itself.

Contents within the Package MUST reference these resources via relative-URL strings [[url]].

Obtaining a Publication Manifest

If the Package contains a publication.json file located in the Root Directory, the Publication Manifest is obtained by opening and parsing this file.

Otherwise, if the Package contains an index.html file located in the Root Directory, the Publication Manifest is obtained through the following steps:

1. Let document be the result of the extraction of the index.html file from the Package.
2. If it does not have the media type text/html or application/xhtml+xml, terminate this algorithm.
3. Let manifest link be the first link element in tree order in document whose rel attribute contains the publication token.
4. If manifest link is null, terminate this algorithm.
5. If manifest link's href attribute's value is the empty string, terminate this algorithm.

6. If the href attribute value of manifest link has a non-null fragment identifying an identifier id in document:

   1. Let embedded manifest script be the first script element in tree order, whose id attribute is equal to id and whose type attribute is equal to application/ld+json.
   2. If embedded manifest script is null, terminate this algorithm.
   3. Let manifest text be the child text content of embedded manifest script
   Explanation

   This branch is in use when the manifest is embedded in the primary entry page. The algorithm locates the script element and extract the manifest itself.

7. Otherwise:
   1. Let manifest URL be the value of the href attribute.
   2. If manifest URL is not a relative URL string, then abort these steps.
   3. Extract the Manifest from the Package using manifest URL.
   4. Open and read the Manifest file, letting manifest text be the result.
   Explanation

   This branch is in use when the manifest is in a separate file. It performs the standard operations to retrieve the manifest from the Package.

If both index.html and publication.json are present in the Package, then the Primary Entry Page SHOULD contain a reference to the publication.json file, following the rules defined in this section.