Data model

Cynario stores one Scenario as readable JSON: metadata, a graph of Scenes and Paths, optional variables/computed values/outcome rules, and settings. Each Scene carries one authoring Mode and a shared data.outputs[] path model; type is only a visual hint.

Normative contract

The source of truth is src/types/scenario.ts. The committed machine-readable contract is the generated Draft 2020-12 schemas/cynario-v2.schema.json. The schema is generated with bun run gen:schema; bun run check:schema refuses drift. This page does not maintain a second hand-written schema.

A current export is a CynarioFile wrapper containing cynario, exported, and scenario. Inside the Scenario, use meta rather than the retired metadata shape, data.outputs[] rather than legacy choices[], and sourceHandle to tie each edge to the output it leaves from.

Scenario-owned cover

A Scenario may carry:

{
  "meta": {
    "cover": {
      "image": "asset:sha256-<64 lowercase hex characters>",
      "focalPoint": { "x": 0.5, "y": 0.4 }
    }
  }
}

The reference and crop metadata live in Scenario JSON; the image bytes do not. Cover bytes must be passive-raster PNG, JPEG, WebP, or AVIF whose MIME matches file magic. SVG, HTML, remote/data URLs, unknown fields, and focal points outside 0..1 are refused. A cover-less Scenario remains valid and uses Cynario’s deterministic abstract fallback.

Use .cynario.zip when content-addressed cover or media bytes must travel with the Scenario. Plain Marketplace publication exposes a verified, hash-bound cover asset as public listing artwork. Protected catalog v3 keeps cover metadata and assets encrypted until unlock; readers remain compatible with protected catalog v1 and v2.

For the detailed model and current v2 example, see the repository’s canonical docs/data-model.md.