Skip to main content
A ScreenJSON file is a JSON document with a stable top-level shape. The authoritative machine-readable definition is the JSON Schema at https://screenjson.com/schema.json.

​
Top-level shape

{
  "id":       "<uuid>",
  "version":  "1.0.0",
  "title":    { "en": "The Heist" },
  "lang":     "en",
  "charset":  "utf-8",
  "dir":      "ltr",
  "authors":  [ /* one or more */ ],
  "document": { "cover": { ... }, "scenes": [ ... ] }
}

​
Required root properties

PropertyTypeDescription
iduuidRFC 4122 document identifier.
versionsemver stringScreenJSON schema version the document was authored against.
titlelanguage mapTitle keyed by BCP 47 language tag.
langBCP 47Primary language.
charsetstringIANA character set label. Default utf-8.
dirltr | rtlText direction.
authorsarrayOne or more author entries.
documentobjectThe screenplay container — cover, scenes, optional layout and bookmarks.

​
Optional root properties

generator, locale, contributors, characters, colors, sources, registrations, revisions, encrypt, license, taggable, genre, themes, logline, analysis. See specification/document-root for the complete description.

​
Commitments

  • Structural, not presentational. Slug, action, cue, parenthetical, dialogue, shot, transition are typed nodes — not layout hints. Rendering lives in the optional layout block.
  • Language as first-class. Every user-facing text field is a BCP 47 keyed map.
  • Stable identity. Every referenceable node carries a UUID.
  • Extensible without ambiguity. Extension data lives only in meta; core fields are additionalProperties: false.
  • Analysis is additive. Embeddings, passages, summaries live under analysis and are discardable.