Livello 1panelwave.json · CC BY 4.0
JSON Schema 2020-12 · CC BY 4.0
Un formato aperto per graphic novel pensate per lo schermo
panelwave.json descrive un’intera opera: vignette e livelli, layout di pagina per ogni schermo, balloon a testo vivo, video e suono, il grafo narrativo, le varianti e le regole del paywall. Pubblico, documentato, versionato. I tuoi contenuti, il tuo formato.
{
"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" }
}
}StrutturaUndici proprietà di primo livello · tre obbligatorie
Un modello di dati completo per il racconto
Ogni ID è una stringa, ogni testo visibile al pubblico è una mappa di locale BCP-47, e i campi personalizzati trovano posto sotto x-.
| Proprietà | Obbligatoria | Cosa contiene |
|---|---|---|
| panelwave | sì | Versione del formato e riferimento allo schema |
| meta | sì | Titolo, autori, lingue, personaggi, classificazione per età, avvertenze sui contenuti, licenza |
| chapters | sì | Vignette, il grafo narrativo, layout di pagina per formato, tela infinita facoltativa |
| assets | — | Immagini, video, audio, sottotitoli con varianti responsive; cartelle |
| variables | — | Variabili narrative tipizzate in cinque ambiti |
| settings | — | Tipografia, preset dei balloon, impostazioni predefinite dell’interfaccia, precaricamento, preset dei formati |
| localization | — | Stato delle traduzioni e glossario (metadati di lavorazione) |
| extras | — | Copertine, schede dei personaggi, interviste, illustrazioni bonus, dietro le quinte |
| paywall | — | Regole per opera, capitolo, vignetta o extra; prodotti |
| tracking | — | Misurazione del pubblico nel rispetto del consenso |
| ui | — | Branding e controlli del reader |
EsempiFrammenti validi secondo lo schema
Copia, incolla, valida
Ecco come appare
{
"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 } }
]
}
}StrumentiLavorare con i file PanelWave
Schema · formato 1.7.0JSON Schema 2020-12Valida con AJV o con qualsiasi validatore 2020-12.GitHub @panelwave/cli 1.2.0 · MITvalidate · bundle · diff · upgradenpx @panelwave/cli validate panelwave.json: funziona offline e include il formato 1.7.0.npm @panelwave/types 1.2.0 · MITTipi TypeScriptOgni definizione dello schema come interfaccia TypeScript, fino al formato 1.7.0.npm
Versioni attuali (4 ott 2026): formato 1.7.0 · @panelwave/cli 1.2.0 · @panelwave/types 1.2.0 · @panelwave/player 1.2.0 · @panelwave/mcp 0.1.0 — quale formato supporta ogni versione
RevisioniVersionato e stabile
Versioni solo additive. Un file 1.0 resta valido.
Le versioni minori si limitano ad aggiungere: nulla smette di funzionare. La versione attuale è la 1.7.0: i capitoli lineari possono fare del tutto a meno dei collegamenti e seguire l’ordine delle vignette, e le scelte hanno etichette proprie.
CC BY 4.0Schema · documentazione
| 1.7 | ott 2026 | I capitoli senza collegamenti seguono l’ordine delle vignette; scelte con etichetta, hotspot mostrati come pulsanti, colore del lettering, ID delle variabili in snake_case, campi x- su vignette ed extra |
| 1.6 | set 2026 | Più prodotti per regola di paywall, informazioni di visualizzazione dei prodotti, animazioni a keyframe dei livelli, copertine alternative, schede di gruppo dei personaggi |
| 1.5 | ago 2026 | Archivio portabile dell’opera: cartelle degli asset e stato delle traduzioni |
| 1.4 | lug 2026 | Tela infinita: posizionamento in coordinate globali, movimenti di camera lungo i collegamenti, lettura verticale in stile webtoon dallo stesso modello |
| 1.3 | lug 2026 | Preset di stile per testo e balloon; la didascalia del narratore come decimo tipo di balloon |
| 1.2 | lug 2026 | Manifest più snelli: tipi MIME facoltativi, transizioni ereditate |
| 1.1 | lug 2026 | Vignette video: modalità di riproduzione, modalità di avvio, varianti al contrario, poster |
| 1.0 | 1° trim. 2026 | Vignette, capitoli, flusso del grafo, asset, variabili + JSON Logic, testo multilingue, formati di uscita, paywall, tracciamento, plugin |
Aiutaci a dare forma allo standard.
Segnala problemi, proponi miglioramenti o invia una pull request. Aperto, versionato, pensato per chi crea.