Schema Overview
Introduction to the PanelWave manifest format — an open JSON Schema for interactive graphic novels with panels, layers, branching, and localization.
The PanelWave manifest is a single JSON document (panelwave.json) that describes an entire interactive graphic novel: its metadata, media assets, chapters, panels, layered artwork, speech bubbles, branching flow graph, variables, and monetization rules. The manifest is the contract between every tool in the PanelWave ecosystem — whatever reads or writes PanelWave content validates against the same schema.
The schema at a glance
| Schema draft | JSON Schema 2020-12 |
Schema $id | https://panelwave.org/schema/1.0/panelwave.schema.json (identifier only — not publicly served yet; get the file from the repository below) |
| Current format version | 1.7.0 (published in-place in the 1.0/ major-version directory) |
| Tooling | @panelwave/cli 1.2.0 and @panelwave/types 1.2.0 (format 1.7.0), @panelwave/player 1.2.0 — see Current releases |
| License | CC BY 4.0 — free to share and adapt with attribution |
| File | 1.0/panelwave.schema.json in panelwave/schema on GitHub |
| Feedback | github.com/panelwave/schema/issues |
The schema license covers the format definition itself. It does not restrict content you create in the PanelWave format (your work remains yours) or software that reads or writes manifests.
Design goals
- Human-readable and writable JSON. You can author a manifest by hand; string IDs are used everywhere instead of array indices.
- Graph-based storytelling. Panels are nodes in a directed graph; edges carry transitions and JSON Logic conditions for branching narratives. See Graph.
- Localization first. All user-facing text is a
LocalizedStringkeyed by BCP-47 locale; assets can be localized too. See Manifest Structure for the shared primitives. - Multiple output formats. One manifest targets web (portrait/landscape), print (A4/US), and video (16:9) via format presets and per-panel format views. See Settings.
- Extensibility. Custom properties prefixed with
x-are allowed at the manifest root, on panels and on extras blocks (since 1.7); a plugin system covers specialized content. See Extensions. - Robustness. Locale fallback chains, conditional content via variables, preload strategies, and memory budget hints support graceful degradation.
- Monetization and accessibility built in. Paywall rules, entitlements, age gates, alt texts, captions, and transcripts are part of the format, not bolted on.
Top-level structure
A manifest is an object with three required and seven optional top-level properties. Unknown properties are rejected (additionalProperties: false), except custom ones matching ^x-.
| Property | Type | Required | Description |
|---|---|---|---|
panelwave | PanelwaveHeader | Yes | Format version and schema URI. See Versioning |
meta | Meta | Yes | Work metadata: title, creators, locales, characters. See Meta |
chapters | Chapter[] (min 1) | Yes | Chapters with panels, pages, and the flow graph. See Chapters & Pages |
assets | Assets | — | Asset catalog and base URLs. See Assets |
variables | Variables | — | Variable definitions for conditional logic. See Variables |
settings | Settings | — | Typography, UI defaults, preload, output presets. See Settings |
extras | Extras | — | Bonus content: covers, character sheets, art. See Extras |
paywall | Paywall | — | Entitlement and paywall rules. See Paywall |
tracking | Tracking | — | Analytics events and consent configuration. See Tracking |
ui | UISettings | — | Branding colors and reader control toggles. See UI |
localization | Localization | — | Since 1.5: translation workflow state (authoring metadata; renderers may ignore). See Versioning |
A minimal but complete annotated example lives in Manifest Structure.
How the ecosystem consumes the schema
@panelwave/typesmirrors every schema$defsentry as a TypeScript interface (PanelwaveManifest,Meta,Chapter,Panel,Layer, …) with the same names used throughout this reference.@panelwave/clivalidates manifests against its bundled copy of the schema (see Validation and CLI), bundles manifest directories, diffs two manifests, and upgrades older manifests.- The player (
@panelwave/player) renders a validated manifest in the browser. See Player Overview. - The CMS authors manifests visually and exports them; it embeds the open-source player for preview so rendering behavior is never duplicated. See CMS Overview.
The types and the CLI are developed in the panelwave/packages monorepo and install from npm:
npm install @panelwave/types # TypeScript interfaces (type-only)
npm install -g @panelwave/cli # the `panelwave` command
When the format evolves, the schema changes first — types, CLI, player, and CMS follow. If a tool and this reference ever disagree, the schema file is authoritative.