Schemas and Artifacts#

OpenMontage defines all structured data exchanged across pipeline stages using JSON schemas. These contracts live under schemas/ and cover checkpoints, pipeline manifests, style playbooks, and 11+ canonical artifacts. Every artifact is validated with jsonschema before a checkpoint is written. Invalid data blocks progression.

Canonical Stage-to-Artifact Mapping#

The system maps each stage to exactly one primary artifact. A checkpoint with status completed or awaiting_human must include the canonical artifact for its stage.

Supplementary artifacts (source_media_review, final_review, video_analysis_brief, review, cost_log) may appear alongside the canonical ones when required by governance rules.

See Checkpoint System for how these artifacts are persisted and Pipeline System for stage ordering.

Artifact Schemas#

All artifacts are versioned JSON objects. Key required fields include:

• script: version, title, total_duration_seconds, sections[] (each with id, text, start_seconds, end_seconds). Optional per-section fields cover speaker_directions, enhancement_cues, and pronunciation_guides.
• scene_plan: version, scenes[] (each with id, type, description, start_seconds, end_seconds). Scenes declare framing, movement, transition_in/out, and required_assets.
• edit_decisions: version, cuts[] (each with id, source, in_seconds, out_seconds), render_runtime (locked value: remotion, hyperframes, or ffmpeg).
• proposal_packet: version, concept_options[] (at least three), selected_concept, production_plan (includes render_runtime, delivery_promise, provider_rankings), cost_estimate, approval.
• asset_manifest: version, assets[] (each with id, type, path, source_tool, scene_id).
• research_brief, render_report, and publish_log follow the same pattern with stage-specific top-level keys.

See Provider Selection for how delivery_promise and provider_rankings are populated inside proposal_packet.

Checkpoint Schema#

Checkpoints wrap artifacts and state:

{
  "version": "1.0",
  "project_id": "my-video",
  "pipeline_type": "cinematic",
  "stage": "script",
  "status": "completed",
  "timestamp": "2026-03-28T10:00:00Z",
  "artifacts": { "script": { ... } },
  "checkpoint_policy": "guided",
  "human_approval_required": false,
  "cost_snapshot": { ... },
  "review": { ... }
}

Status values are pending, in_progress, awaiting_human, completed, or failed. Checkpoints are written to the project pipeline/ directory.

Pipeline Manifests#

Pipeline definitions are YAML files validated against the pipeline manifest schema. A minimal manifest declares:

name: cinematic
version: "2.0"
category: cinematic
default_checkpoint_policy: guided
orchestration:
  mode: executive-producer
  budget_default_usd: 2.00
stages:
  - name: research
    skill: pipelines/cinematic/research-director
    produces: [research_brief]
    tools_available: []
    checkpoint_required: true
    human_approval_default: false

See Available Pipelines for the full list and Running Pipelines for manifest usage.

Style Playbooks#

Playbooks are YAML files validated against the style schema. They define identity, visual_language, typography, motion, audio, and asset_generation rules. Pipelines declare compatible_playbooks in their manifest. The chosen playbook is locked in proposal_packet.production_plan.playbook and carried forward.

See Style Playbooks for built-in options and custom playbook rules.

Validation Rules#

• Schemas are enforced at checkpoint write time.
• render_runtime and delivery_promise values locked at proposal must match in later artifacts.
• Missing a canonical artifact for a completed stage fails validation.
• All artifacts under projects/<kebab-name>/artifacts/ and inside checkpoints must conform.

See Cost Tracking and Governance Issues for how validation interacts with budget and delivery rules.