Skip to content
This repository was archived by the owner on Sep 23, 2026. It is now read-only.

Scene JSON and Schemas

Jump to bottom
kunail0804 edited this page Jul 16, 2026 · 4 revisions

Scene JSON & Schemas

Spec reference: MASTER_SPEC §10–11.

Scene JSON is the compiler's Intermediate Representation (IR) and its stable public interface. This page defines its semantic grammar — which concepts may exist and where — and the JSON Schemas that guarantee interoperability between stages.

Root structure

A Scene always contains these top-level sections. All sections must exist; empty sections are empty arrays (and metadata an object).

Scene
├── characters    (0..N)
├── interactions  (0..N)
├── objects       (0..N)
├── environment   (0..N concepts)
├── camera        (0..N concepts)
├── lighting      (0..N concepts)
└── metadata

Example

Input: "A blonde girl wearing a white dress hugs a young man while walking under the rain."

{
  "characters": [
    { "id": 0, "identity": ["female"], "appearance": ["blonde hair"],
      "clothing": ["white dress"], "accessories": [], "pose": [],
      "expression": [], "actions": [] },
    { "id": 1, "identity": ["male"], "appearance": [], "clothing": [],
      "accessories": [], "pose": [], "expression": [], "actions": [] }
  ],
  "interactions": [ { "participants": [0, 1], "concept": "hug" } ],
  "objects": [],
  "environment": ["rain"],
  "camera": [],
  "lighting": [],
  "metadata": {}
}

Grammar rules

  • Characters — every human, creature, or identifiable subject; each is independent; order reflects discovery order. Fields follow the Data Model.
  • Interactions — relationships between two or more characters; belong to the scene, never to a character.
  • Environment / Objects / Camera / Lighting — arrays of semantic concepts. Camera and lighting appear only when explicitly described. Objects are not owned by characters unless explicitly stated.
  • Cardinality — characters, interactions, objects, environment, camera, lighting are each 0..N.
  • Ordering — preserved. Concepts appear in discovery order; the compiler never reorders semantic concepts.
  • Unknown concepts — permitted; they remain as plain concepts and must not be removed or replaced. Later stages may emit warnings.
  • One location per concept — e.g. smile belongs to expression (not actions); walking belongs to actions (not pose). The final output category is decided later by the Knowledge Base — see Glossary & Reference.
  • Extensibility — future versions may add sections; existing sections stay backward compatible.

JSON Schemas

Every JSON document exchanged between modules must conform to an official JSON Schema. Invalid JSON must not continue through the pipeline.

The compiler ships nine JSON Schemas:

Schema Key fields
Scene characters, interactions, objects, environment, camera, lighting, metadata (all required; collections may be empty)
Character id (int), identity, appearance, clothing, accessories, pose, expression, actions (arrays of strings or Concept objects)
Concept name (required), category (optional until validation), source (optional), metadata (optional). A bare string equals { "name": <string> }.
Interaction participants (array of Character id), concept (string)
Metadata schema_version, compiler_version, language, warnings
Knowledge Base Entry id, aliases, tags, category, expand, rating (general/explicit), deprecated, notes
Knowledge Base Manifest (V2) dataset version and metadata for a versioned Knowledge Base directory (see Knowledge Base → Versioning)
Configuration the compiler config sections (analyzer, resolver, validator, prompt_builder, semantic, debug)
Resolved Tag tag, category, source_concept, knowledge_base_entry

Validation rules

Schemas validate type correctness, required fields, unknown fields, array types, string types, enum values, and schema version.

Versioning & generation

Every schema carries a major and minor version. Breaking changes bump the major; backward-compatible additions bump the minor. Version 1 guarantees compatibility within the same major version. Future tooling may generate data classes, validation code, docs, and example JSON directly from the schemas.

Related pages

A note on AI assistance

This project — its code, tests, and documentation — is built with heavy help from AI coding assistants and maintained by a solo author. AI makes mistakes: despite testing and review, parts of this may be inaccurate, out of date, or wrong. Treat it as a good-faith best effort, not authoritative truth — if the docs and the code disagree, the code wins. Please open an issue when something looks off.

Clone this wiki locally