# Seedance 2.0 JSON Schema for Structured Prompt Output: Complete Reference

> Explore the Seedance 2.0 JSON Schema for structured prompt output. Discover required fields for complete sequencing metadata and role-based reference handling in generations.

- Repository: [Iamemily2050 /seedance-2.0](https://github.com/Emily2040/seedance-2.0)
- Tags: api-reference
- Published: 2026-08-03

---

**Seedance 2.0 defines a strict JSON Schema in [`schemas/prompt-spec.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/prompt-spec.schema.json) that enforces 11 required fields—including `sequence_relation`, `opening_state_source`, and `natural_language_prompt`—to ensure every generation prompt contains complete sequencing metadata and role-based reference handling.**

The **Prompt Specification schema** governs how all structured prompts must be formatted before submission to the Seedance generation engine. Located in the `Emily2040/seedance-2.0` repository, this JSON Schema 2020-12 draft serves as the contract between client applications and the video generation pipeline, standardizing everything from clip sequencing logic to exclusion management.

## Core Schema Requirements

Every valid prompt must satisfy the schema defined in [[`schemas/prompt-spec.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/prompt-spec.schema.json)](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/prompt-spec.schema.json). The root type is `object` with no optional fields at the top level.

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `project_id` | string | Unique identifier for the parent project |
| `clip_id` | string | Unique identifier for this specific clip |
| `prompt_version` | string | Semantic version of the prompt schema (e.g., `2.0.0`) |
| `sequence_relation` | enum | Relationship to preceding clips: `standalone`, `sequence_first_clip`, `seamless_continuation`, `intentional_next_shot`, `bridge_between_known_states`, `repair_tail`, `reanchor_after_drift` |
| `generation_mode` | string | Processing mode: typically `standard` or `draft` |
| `reference_roles` | array[string] | Roles providing reference material (e.g., `director`, `cinematographer`) |
| `opening_state_source` | enum | How the initial frame state is determined: `planned_start_state`, `observed_end_state`, `user_supplied_final_frame`, `source_clip` |
| `current_clip_action` | string | Description of intended action for this clip |
| `endpoint` | string | Target generation endpoint URL or identifier |
| `completed_beat_exclusions` | array[string] | Beat identifiers that must **not** be regenerated |
| `reserved_future_exclusions` | array[string] | Beat identifiers reserved for future generation |
| `natural_language_prompt` | string (minLength: 1) | Human-readable generation instructions |

The schema enforces `minLength: 1` on `natural_language_prompt` to prevent empty submissions. All arrays contain homogeneous string items with no additional constraints on the values themselves.

## Sequence Relation Enum Values

The `sequence_relation` field controls how Seedance 2.0 handles temporal continuity between clips:

- **`standalone`** — Independent clip with no sequential dependencies
- **`sequence_first_clip`** — Opening clip of a multi-clip sequence
- **`seamless_continuation`** — Strict continuity from previous clip's end state
- **`intentional_next_shot`** — Deliberate cut or perspective change
- **`bridge_between_known_states`** — Interstitial clip connecting two established states
- **`repair_tail`** — Corrective generation replacing a failed previous ending
- **`reanchor_after_drift`** — Recovery generation when sequence coherence degrades

## Opening State Source Options

The `opening_state_source` enum determines frame initialization:

| Value | Use Case |
|-------|----------|
| `planned_start_state` | Pre-defined storyboard or shot list state |
| `observed_end_state` | Actual rendered output from previous clip |
| `user_supplied_final_frame` | Custom reference image provided by user |
| `source_clip` | Direct extraction from existing source material |

## JSON Schema Examples

### Minimal Valid Prompt (Standalone Clip)

```json
{
  "project_id": "proj-1234",
  "clip_id": "clip-01",
  "prompt_version": "2.0.0",
  "sequence_relation": "standalone",
  "generation_mode": "standard",
  "reference_roles": ["director", "cinematographer"],
  "opening_state_source": "planned_start_state",
  "current_clip_action": "establish_scene",
  "endpoint": "https://api.seedance.ai/v2/generate",
  "completed_beat_exclusions": [],
  "reserved_future_exclusions": [],
  "natural_language_prompt": "Create a wide-angle opening shot of a bustling city at dawn."
}

```

As implemented in `Emily2040/seedance-2.0`, this is the smallest payload that passes schema validation—all 11 fields present with valid types and non-empty natural language content.

### Sequential Continuation (Multi-Clip Sequence)

```json
{
  "project_id": "proj-1234",
  "clip_id": "clip-02",
  "prompt_version": "2.0.0",
  "sequence_relation": "seamless_continuation",
  "generation_mode": "standard",
  "reference_roles": ["director"],
  "opening_state_source": "observed_end_state",
  "current_clip_action": "follow_character",
  "endpoint": "https://api.seedance.ai/v2/generate",
  "completed_beat_exclusions": ["beat-01"],
  "reserved_future_exclusions": ["beat-04"],
  "natural_language_prompt": "Continue following the protagonist as they enter the subway, maintaining the established lighting."
}

```

This example demonstrates **exclusion management**: `completed_beat_exclusions` prevents regeneration of `beat-01`, while `reserved_future_exclusions` protects `beat-04` for later manual creation.

### Draft Mode with Custom State Source

```json
{
  "project_id": "proj-5678",
  "clip_id": "clip-07",
  "prompt_version": "2.0.1",
  "sequence_relation": "intentional_next_shot",
  "generation_mode": "draft",
  "reference_roles": ["editor", "storyboard_artist"],
  "opening_state_source": "user_supplied_final_frame",
  "current_clip_action": "transition_to_climax",
  "endpoint": "https://api.seedance.ai/v2/generate",
  "completed_beat_exclusions": ["beat-03", "beat-05"],
  "reserved_future_exclusions": ["beat-09"],
  "natural_language_prompt": "Generate a high-energy chase sequence that picks up immediately after the previous beat, emphasizing motion blur."
}

```

The `draft` generation mode reduces processing cost for iteration, while `intentional_next_shot` signals a deliberate discontinuity from the previous clip's visual flow.

## Schema Validation and Tooling

The Seedance 2.0 repository provides several files to enforce and test the prompt specification:

| File | Purpose |
|------|---------|
| [`schemas/prompt-spec.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/prompt-spec.schema.json) | Canonical schema definition |
| [`schemas/generation-run.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/generation-run.schema.json) | Parent schema wrapping one or more prompts |
| [`validation/fixtures/prompt-spec.valid.json`](https://github.com/Emily2040/seedance-2.0/blob/main/validation/fixtures/prompt-spec.valid.json) | CI-tested valid example |
| [`scripts/prompt_lint.py`](https://github.com/Emily2040/seedance-2.0/blob/main/scripts/prompt_lint.py) | CLI validator for local development |

Run validation locally against the JSON Schema:

```bash
python scripts/prompt_lint.py --schema schemas/prompt-spec.schema.json --prompt my-prompt.json

```

The lint script loads the schema and uses a JSON Schema validator to report any missing required fields or type violations.

## Integration with Generation Runs

Individual prompts conforming to this schema are embedded within larger **generation run** payloads. The [`schemas/generation-run.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/generation-run.schema.json) file defines the container structure that batches multiple prompts for pipeline execution, ensuring each element passes the prompt specification before submission to the rendering engine.

## Summary

- **Seedance 2.0 structured prompt output** requires exactly 11 fields defined in [`schemas/prompt-spec.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/prompt-spec.schema.json)
- The `sequence_relation` enum provides 7 values for continuity control, from `standalone` to `reanchor_after_drift`
- `opening_state_source` determines frame initialization: planned, observed, user-supplied, or source-derived
- `natural_language_prompt` enforces `minLength: 1` to prevent empty submissions
- Exclusion arrays (`completed_beat_exclusions`, `reserved_future_exclusions`) manage beat-level generation scope
- Use [`scripts/prompt_lint.py`](https://github.com/Emily2040/seedance-2.0/blob/main/scripts/prompt_lint.py) for local validation against the canonical schema

## Frequently Asked Questions

### What version of JSON Schema does Seedance 2.0 use?

Seedance 2.0 uses **JSON Schema 2020-12 draft** as specified in the `$schema` declaration of [`schemas/prompt-spec.schema.json`](https://github.com/Emily2040/seedance-2.0/blob/main/schemas/prompt-spec.schema.json). This modern draft supports advanced validation features while maintaining broad tooling compatibility.

### Can I submit a prompt with partial fields?

No. All 11 fields are **required** at the schema level—there are no optional top-level properties. Omitting any field causes validation to fail in [`scripts/prompt_lint.py`](https://github.com/Emily2040/seedance-2.0/blob/main/scripts/prompt_lint.py) and rejection by the generation pipeline.

### How do I prevent specific beats from being regenerated?

Populate the `completed_beat_exclusions` array with string identifiers for beats that must be preserved. For beats you plan to create manually later, use `reserved_future_exclusions`. Both arrays accept any string format your project uses for beat identification.

### Where can I find a working example of a valid prompt?

The file [`validation/fixtures/prompt-spec.valid.json`](https://github.com/Emily2040/seedance-2.0/blob/main/validation/fixtures/prompt-spec.valid.json) contains a CI-tested valid prompt that passes schema validation. Use this as a starting template, or run `python scripts/prompt_lint.py` against your own payloads to verify compliance before API submission.