An open format for graphic novels made for screens

panelwave.json describes a whole work — panels and layers, page layouts per screen, live-text balloons, video and sound, the story graph, variants and paywall rules. Public, documented, versioned. Your content, your format.

Browse the schema Read the docs

panelwave.json

{
  "id": "sb-07",
  "characterId": "mira",
  "text": {
    "en-US": "Something's not right here.",
    "de-DE": "Hier stimmt etwas nicht.",
    "ja-JP": "何かがおかしい。"
  },
  "shape": { "x": 0.58, "y": 0.06, "w": 0.32, "h": 0.16 },
  "balloonConfig": {
    "balloonType": "whisper",
    "tail": { "position": 210, "length": 40, "curve": "left" }
  }
}

StructureEleven top-level properties · three required

A complete storytelling data model

Every ID is a string, every user-facing text a map of BCP-47 locales, and custom fields are welcome under x-.

Property	Required	What it holds
panelwave	yes	Format version and schema reference
meta	yes	Title, creators, locales, characters, age rating, content warnings, licence
chapters	yes	Panels, the story graph, page layouts per format, optional infinite canvas
assets	—	Images, video, audio, subtitles with responsive variants; folders
variables	—	Typed story variables in five scopes
settings	—	Typography, balloon presets, UI defaults, preloading, format presets
localization	—	Translation state and glossary (authoring metadata)
extras	—	Covers, character sheets, interviews, bonus art, behind the scenes
paywall	—	Rules per work, chapter, panel or extras; products
tracking	—	Consent-aware event tracking
ui	—	Branding and reader controls

SamplesSchema-valid snippets

Copy, paste, validate

What it looks like

Linear chapter

{
  "id": "ch-01",
  "title": { "en-US": "Night Shift" },
  "panels": {
    "p1": { "layers": [{ "id": "art", "kind": "image", "assetId": "img-p1" }] },
    "p2": { "layers": [{ "id": "art", "kind": "image", "assetId": "img-p2" }] },
    "p3": { "layers": [{ "id": "art", "kind": "image", "assetId": "img-p3" }] }
  },
  "graph": {
    "entry": "p1",
    "edges": [
      { "from": "p1", "to": "p2" },
      { "from": "p2", "to": "p3", "transition": { "type": "fade", "durationMs": 400 } }
    ]
  }
}

ToolsWorking with PanelWave files

Schema · format 1.7.0JSON Schema 2020-12Validate with AJV or any 2020-12 validator.GitHub @panelwave/cli 1.2.0 · MITvalidate · bundle · diff · upgradenpx @panelwave/cli validate panelwave.json — works offline, bundles format 1.7.0.npm @panelwave/types 1.2.0 · MITTypeScript typesEvery schema definition as a TypeScript interface, up to format 1.7.0.npm

Current releases (4 Oct 2026): format 1.7.0 · @panelwave/cli 1.2.0 · @panelwave/types 1.2.0 · @panelwave/player 1.2.0 · @panelwave/mcp 0.1.0 — which format each release supports

RevisionsVersioned and stable

Additive releases. A 1.0 file still validates.

Minor versions only add; nothing breaks. The current release is 1.7.0: linear chapters can skip edges entirely and follow the panel order, and choices carry their own labels.

CC BY 4.0Schema · docs

1.7	Oct 2026	Chapters without edges follow the panel order; labelled choices, hotspots shown as buttons, lettering colour, snake_case variable ids, x- fields on panels and extras
1.6	Sep 2026	Several products per paywall rule, product display info, layer keyframe animations, alternative covers, ensemble character sheets
1.5	Aug 2026	Portable work archive: asset folders and translation state
1.4	Jul 2026	Infinite canvas: world-space placements, camera moves along edges, webtoon-style vertical reading from the same model
1.3	Jul 2026	Style presets for text and balloons; the narrator caption as tenth balloon type
1.2	Jul 2026	Leaner manifests: optional MIME types, inherited transitions
1.1	Jul 2026	Video panels: play modes, start modes, reverse variants, posters
1.0	Q1 2026	Panels, chapters, graph flow, assets, variables + JSON Logic, multilingual text, output formats, paywall, tracking, plugins

Help shape the standard.

Report issues, propose enhancements or send a pull request. Open, versioned and built for creators.

The schema on GitHub The open-source player