GNML · General Narrative Markup Language

An open standard for organizing story

GNML describes a narrative as structured data: who is in it, where and when things happen, what each event changes, and where in the text each fact comes from. Once a story is organized this way, anything can be attached to it, and everything attached stays consistent.

The idea

Structure before pictures

Most tools that turn stories into images or media go straight from words to output. GNML puts a model of the story in between, so that thousands of maps, panels and pages can be made from it without contradicting the text or each other.

The usual wayText → Prompt → Image

With GNMLText → Structured story → Visual logic → Output

The layers

Six layers, one story

Layer	What it holds	In the Shahnameh
Canon	The source text, with a permanent address for every line	51,547 couplets, cited as book.section.couplet
Narrative	Episodes, scenes and events, in order	951 sections and the dastans
State	Who and what exists, how they are related, and what is true at each point in the story	1,128 registry entries, 178 family links, 26 plates
Visual	Renderable descriptions of people, places and scenes	99 story maps, manga panels, Pahlevan banners
Product	The outputs derived from the story	Book, website, emoji edition, numbers
Constraint	Rules that keep it all consistent	One ID per person; every claim traced to a couplet

Principles

What GNML insists on

Everything has an addressEvery line, scene, person and event has a unique ID, and every reference must resolve.

One registryEach entity is defined once and referred to everywhere, which is what makes continuity enforceable.

Events change stateA death, a marriage, a wound is recorded as a change, and later scenes must respect it.

Every claim has a sourceFacts carry their source lines and say whether they are explicit, inferred or uncertain.

Outputs are viewsA book, a map, a panel or a timeline is derived from the structure, never edited apart from it.

A worked example

Rakhsh and the lion, layer by layer

The first of Rostam’s seven labors, section B5.1: Rostam sleeps, a lion comes, and his horse Rakhsh kills it. Here is the same moment in each layer.

Canon · B5.1.17–19

He sprang; but Rakhsh, like fire, rose in flame,And charged the lion as the lion came.He struck its head with both forelegs in rage,Then seized its back, his sharpened jaws a cage.He smashed the lion hard against the ground,And tore it till no trace of life was found.Ferdowsi, Shahnameh B5.1.17–19, tr. Farzad and Rhonda Dibachi

State · the registry

Rakhshرخش · rakhsh
Rostam's horse, rose-colored and dappled, chosen from the herds of Zabul. Wounded with Rostam by Esfandiyar and healed by the Simorgh, it dies with him in Shaghad's pit.Horse · named 7 times in this section

Rostamرستم · rostam-i-ii-iii
Son of Zal and Rudabeh, the greatest Pahlevan of Iran; also called Tahamtan and Piltan. He slays Esfandiyar and dies through his half-brother Shaghad's treachery.The registry keeps him apart from rostam-iii, a later Rostam of the same name.

Narrative · scene and events

# Illustrative GNML (draft v0.3): the first labor, B5.1
scene:
  id: B5.1/lion
  location: place:wilderness
  time_of_day: night
  participants: [rostam-i-ii-iii, rakhsh, creature:lion]
events:
  - id: lion-approach    type: movement   agents: [creature:lion]   source: B5.1.16
  - id: rakhsh-attacks   type: attack     agents: [rakhsh]  targets: [creature:lion]   source: B5.1.17
  - id: lion-killed      type: killing    agents: [rakhsh]  targets: [creature:lion]   source: B5.1.19
    effects: [ creature:lion → alive: false ]
  - id: rostam-wakes     type: awakening  agents: [rostam-i-ii-iii]   source: B5.1.20
    effects: [ rostam-i-ii-iii → sleeping: false ]
provenance:
  status: explicit      # stated in the verse, not inferred
  confidence: high

Visual · panels, one per event

Manga panel: The lion comes upon the camp — `lion-approach`The lion comes upon the camp

Manga panel: Rakhsh rises to meet it — `rakhsh-attacks`Rakhsh rises to meet it

Manga panel: The strike — `rakhsh-attacks`The strike

Manga panel: The lion destroyed — `lion-killed`The lion destroyed

Product · the emoji edition

😴🦁🐎💀
🏇💪🐎🌃🦓🪢🔥🍖😴🦁👀🐎⚔️🦁💀👨😴🌅🐎🤗🙏

Product · every view of B5.1

The verse The Seven Labors, with panels and map The notes The emoji telling Rostam’s page

The reference implementation

The Shahnameh as a data set

The Shahnameh is the first full world built on GNML, and one of the longest poems ever written by a single author. If the method holds here, it holds for any story.

51,547couplets, each addressable

951sections

1,128registry entries

31,148tagged mentions

178family links

18,215emoji, one layer of many

Status

Where GNML stands

GNML is a working draft, at version 0.3. Version 0.4 will add a richer catalogue of event types, a system for motifs, and links between texts. It will be published as an open standard that anyone may implement.

Licenses. The GNML specification is released under the Creative Commons Attribution 4.0 license (CC BY 4.0), and the GNML code under the Apache License 2.0. Use it, extend it and build on it, commercially or not, with credit.

The names GNML and New Naqqali are trademarks of New Naqqali LLC, so that what carries the name is the standard itself.

Interested in using GNML, or in bringing a story to it? Write to Editor@newnaqqali.com.