Back to BookField

BookField package format

wbpkg

wbpkg is the installable content package format that BookField imports for local-first reading, offline search, study plans, and structured references.

Version snapshot

workbook.toml
schema_version = 4
.wbpkg/manifest.json
schemaVersion = 5
reader_manifest.json
schemaVersion = 3
reader.rdoc
schemaVersion = 3
Reader SQLite schema
db_schema_version = 17

At a glance

A package that BookField can validate, install, and read

A wbpkg package contains one work and one edition. It carries the metadata, reader assets, navigation, optional schedules, and locator indexes needed for BookField to validate and install the package on the device.

Installable container

A package is a single installable boundary for one work and one edition.

Manifest v5

manifest.json defines identity, work, edition, assets, navigation, and optional entries.

ReaderDoc v3

ReaderDoc content is prepared for import, so the reader does not parse EPUB, HTML, or CSS at runtime.

Navigation tree

navigationTree decides the entry point and the reader's package-level table of contents.

Locator indexes

Locator indexes and bindings resolve authored references offline when matching packages are installed.

Study plans

Authored study plans live in manifest.json only when the package includes schedule data.

Package layout

Canonical files inside a wbpkg

Package paths are package-root-relative POSIX paths. Text packages include ReaderDoc files under reader/, while image, audio, or video only packages may omit reader/ when they have no text asset.

.wbpkg
manifest.json
reader/{assetId}/reader_manifest.json
reader/{assetId}/reader.rdoc
images/{assetId}.{ext}
images/{assetId}-thumb.{ext}
media/{assetId}.{ext}
locator/{profileId}.json

Manifest contract

Manifest v5 defines the install contract

manifest.json is the public contract that BookField reads before import. Legacy packageKind and presentation fields are not part of the current package shape.

packageId / packageVersion

Defines the package identity and package version used for install and replacement decisions.

work / edition

Identifies the work and the edition contained by the package.

assets

Lists text, image, audio, and video assets and the local paths that belong to each asset.

navigationTree

Defines the entry point and package navigation that the reader can open offline.

studyPlans

Adds authored schedules only when the package includes study plan metadata.

bindings

Connects authored references to locator indexes for offline resolution.

Package creation

Keep production tooling separate from the public package boundary

  1. 1

    Author source content

    Prepare source content, metadata, media, and any authored schedules or references.

  2. 2

    Produce a wbpkg

    Produce an installable package with manifest metadata, ReaderDoc content, media, navigation, and locator files.

  3. 3

    Verify before sharing

    Check the package structure and schema compatibility before distribution.

Reader import

BookField reads the installed package locally

  1. 1

    Validate

    BookField checks the package shape and rejects unsupported or malformed packages.

  2. 2

    Unpack

    Supported package assets are unpacked into app-owned local storage.

  3. 3

    Import into SQLite

    ReaderDoc payloads, navigation, locator indexes, search records, and schedules are registered for offline use.

Compatibility

Rules that keep packages predictable

  • Reject legacy packageKind values.
  • Reject legacy presentation fields.
  • Reject non-canonical package paths.
  • Reject malformed structured references.
  • Do not include source EPUB files in an installable wbpkg.

Canonical references

Update policy

This public page is an implementation-facing overview, not the canonical schema source. The canonical docs and schema files live with the BookField source materials.

Source docs and schema files

  • 00-spec-index.md

    Defines the version policy, shared manifest shape, package layout, path rules, study-plan storage, and locator policy that this page summarizes.

  • 04-manifest-json-schema.md

    Defines the manifest v5 contract, required navigationTree, package-root-relative paths, semantic validation boundary, and rejection rules.

  • 08-reader-app-design.md

    Defines how BookField validates, unpacks, imports ReaderDoc data into SQLite, and reads installed packages locally.

  • schemas/manifest-v5.schema.json / readerdoc-v3.schema.json

    Provide the structural schemas for manifest.json and ReaderDoc payloads used by validation tooling.

When the canonical docs or schema files change, update the source first, then refresh this public snapshot and its explanation.

Plan BookField package distribution

Return to the product overview, or discuss whether a wbpkg distribution flow fits your content model.

Back to BookField Discuss content distribution