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 in the private source repository. The committed machine-readable contract is the generated Draft 2020-12 schemas/cynario-v3.schema.json. Authenticated collaborators can inspect both paths in a reviewed checkout. 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.

The current schema version is 3.0. The frozen schemas/cynario-v2.schema.json remains available as the historical 2.x contract; current saves and exports always emit canonical 3.0.

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.

Image Scenes

Image Mode is additive. A Scene stores a canonical local asset:sha256-… reference and either a trimmed description (maximum 1,000 characters) or an explicit decorative declaration. Supported bytes are passive-raster PNG, JPEG, WebP, and AVIF only; SVG, GIF, HTML, remote/data/blob paths, MIME/signature mismatches, undecodable images, encoded files over 25 MiB, dimensions over 8192, and rasters over 40,000,000 decoded pixels fail closed.

Hotspots remain ordinary Outputs. Image button Outputs use image: { v: 2, geometry }; Video area Outputs use video: { v: 1, geometry, start, end, ... }. Both share one normalized 0..1 geometry union: contained rectangles or polygons with 3–64 { x, y } points and no repeated closing point. Polygon bounds are derived rather than persisted. Geometry changes presentation only—the Output ID, Rules/effects, Path, runtime activation, and PlayLog remain authoritative. Invalid/unavailable media or malformed geometry restores the ordinary Output affordance, and Scenario 3 rejects legacy output.metadata.region shadows.

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.

The private source repository keeps the detailed model and current v3 example in docs/data-model.md; authenticated collaborators can inspect it in a reviewed checkout.