Document¶

A Document contains the screenplay itself (i.e. the content). It consists of a collection of Scene objects which can inherit its properties, but also allows for fast browsing with a collection of one or more Bookmark objects which are containers on their own for a selection of different content (e.g. annotations). It’s function is similar to that in word processing, but it is exclusively designed to hold data.

Structuring¶

A Document also provides the morphological schema of the screenplay, which can be used by the GUI host to present it visually. Its structural content consists of:

One or more bookmarks (for navigating the content easily)
A single cover page (displaying the title of the work and enforcing consistency)
A single header (displayed on each page)
A single footer (displayed on each page)
A collection of styles (for re-use across the content)
A collection of templates (for re-use across the content)
A collection of revisionable scenes (the actual content)

Note

ScreenJSON does not support multiple cover pages, headers, or footers - or arbitrary content within them (e.g. images). This is deliberate. The purpose of the format is to store the data of a semantic document, not provide a visual representation of the document itself.

Attributes¶

A Document is, in essence, a sub-container of the global container. Its properties are fundamentally the definition of the document content and its structure, which may also be inherited from its parent container.

Individual Properties¶

A Document must include a cover, a header, a footer and its revision status, which explain how to present the content.

Property	Description	Type	Required
cover	A Cover object specifying the cover page content.	object	Yes
footer	A Footer object specifying the footer content.	object	Yes
header	A Header object specifying the header content.	object	Yes
meta	An arbitrary Meta object of custom values.	object	No
status	A Status object showing the script color revision.	object	Yes
templates	List of visual templates which should be applied to the content.	array	No

Collection Properties¶

A Container must include an array of scenes. All other collections are optional.

Property	Description	Type	Required
bookmarks	One or more Bookmark objects.	array	No
scenes	One or more Scene objects.	array	Yes
styles	One or more reusable Style objects.	array	No

Sub-Objects¶

Bookmark¶

A Bookmark describes a shortcut child Element object within a Scene object.

{
  "id": "8537e8d6-758c-439c-af10-f60dd693044a",
  "parent" : "9db20a5b-cece-45be-96a0-c31ecedb721a",
  "scene": 4,
  "type": "action",
  "element": 2,
  "title": {
      "en": "Start"
  },
  "description": {
      "en": ""
  }
}

Property	Description	Type	Required
element	Index of the Element object within the scene.	int	Yes
description	A Content object describing the bookmark.	object	Yes
scene	Index of the Scene element.	int	Yes
parent	Parent identifier of the object being bookmarked.	string	Yes
title	A Title object with the name of the bookmark.	object	Yes
type	The type property of the scene Element.	string	No

Note

The index of a scene or element is analogous to its placement in an array (i.e. the array index). In the example above, the bookmark corresponds to the third element (action) in the fifth scene.

Content¶

A Content block describes a generic piece of text in multiple languages.

{
  "en": "Some text in English",
  "fr": "Quelques textes en français"
}

Property	Description	Type	Required
[lang]	Text in the main language specified in the container.	string	Yes
[iso]	Text in the iso language code specified.	string	No

Cover¶

A Cover describes how the front page of the screenplay should be presented.

{
  "title" : {
    "en": "THE SHAWSHANK REDEMPTION",
    "es-mx": "Sueño de fuga"
  },
  "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
  "meta" : {
    "property": "value"
  },
  "derivations" : ["3608b093-1280-4834-9ea4-d9d2b8d711a6"],
  "additional" : {
    "en" : "Based upon the story Rita Hayworth and Shawshank Redemption by Stephen King"
  }
}

Property	Description	Type	Required
authors	References to the author IDs defined in the parent container.	array[string]	Yes
additional	A Content object with arbitrary text.	string	No
derivations	A list of derivation IDs to include in the cover.	array[string]	No
meta	Arbitrary Meta object of custom properties.	object	No
templates	List of internal templates a GUI host should apply to the content	array[string]	No
title	A Title object with the name of the work.	object	Yes

Footer¶

A Footer describes how the footer bar/ribbon of the screenplay should be presented.

{
  "cover" : true,
  "display" : true,
  "start": 1,
  "omit" : [0],
  "content" : {
    "en" : "(c) __DATE__ Copyright Castle Rock Entertainment. __PAGE__"
  },
  "meta" : {
    "property": "value"
  }
}

Property	Description	Type	Required
cover	Whether or not to show the footer on the cover page.	boolean	Mo
content	A Content object specifying the tex.	object	No
display	Whether or not to display the footer at all.	boolean	No
meta	Arbitrary Meta object of custom properties.	object	No
omit	A list of scenes or page indexes where a footer should not be shown.	array[int]	No
start	A page or scene index where a footer should start to be shown.	int	No

Header¶

A Header describes how the footer bar/ribbon of the screenplay should be presented.

{
  "cover" : true,
  "display" : true,
  "start": 1,
  "omit" : [0],
  "content" : {
    "en" : "THE SHAWSHANK REDEMPTION by Frank Darabont"
  },
  "meta" : {
    "property": "value"
  }
}

Property	Description	Type	Required
cover	Whether or not to show the header on the cover page.	boolean	Mo
content	A Content object specifying the text.	object	No
display	Whether or not to display the header at all.	boolean	No
meta	Arbitrary Meta object of custom properties.	object	No
omit	A list of scenes or page indexes where a header should not be shown.	array[int]	No
start	A page or scene index where a header should start to be shown.	int	No

Meta¶

A Meta object describes a generic or custom set of properties and their values.

{
  "something": "Anything you want",
}

Property	Description	Type	Required
[key]	Any key name.	string	No
[value]	Any value of any type.	mixed	No

Status¶

An Status describes a script revision color.

{
  "color": "blue",
  "round" : 1,
  "updated" : "2004-02-12T15:19:21+00:00",
  "meta" : {
    "property": "value"
  }
}

Property	Description	Type	Required
color	Color code of the revision (see note)	string	Yes
round	Which round of revisions the work is on.	int	Yes
meta	Arbitrary Meta object of custom properties.	object	No
updated	ISO 8601 timezone date the revision was last updated.	string	Yes

Industry standard revision colors:

white
blue
pink
yellow
green
goldenrod
buff
salmon
cherry

Style¶

Similar to a CSS declaration, a Style defines a reusable visual rule a GUI should apply to the content of one or more scene elements throughout the entire document.

{
  "id" : "courier-12",
  "default": true,
  "content" : "font-family: courier; font-size: 12px;",
  "meta" : {
    "property": "value"
  }
}

Property	Description	Type	Required
id	Unique sluggable identifier for referencing within the document.	string	Yes
content	Arbitrary text with instructions for the presentation rule.	string	Yes
default	Whether or not the style should be the default presentation.	boolean	No
meta	Arbitrary Meta object of custom properties.	object	No

Warning

ScreenJSON is not a presentation format. A Style object is used by the GUI host to store the data it needs to present the document content, which it defines itself. How a screenplay appears is up to the host, this object allows it to store the data of the instruction.

Document Example¶

A blank document could be expressed as the following:

Example ScreenJSON document object with simplistic values¶

{
  "bookmarks" : [
    {
      "id": "8537e8d6-758c-439c-af10-f60dd693044a",
      "parent" : "9db20a5b-cece-45be-96a0-c31ecedb721a",
      "scene": 4,
      "type": "action",
      "element": 2,
      "title": {
          "en": "Third element (action) block in scene 5"
      },
      "description": {
          "en": ""
      }
    }
  ],
  "cover": {
      "title" : {
        "en": "THE SHAWSHANK REDEMPTION",
        "es-mx": "Sueño de fuga"
      },
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "meta" : {
        "property": "value"
      },
      "derivations" : true,
      "additional" : {
        "en" : "Based upon the story Rita Hayworth and Shawshank Redemption by Stephen King"
      }
  },
  "footer" : {
      "cover" : true,
      "display" : true,
      "start": 1,
      "omit" : [0],
      "content" : {
        "en" : "(c) __DATE__ Copyright Castle Rock Entertainment. __PAGE__"
      },
      "meta" : {
        "property": "value"
      }
  },
  "header" : {
      "cover" : true,
      "display" : true,
      "start": 1,
      "omit" : [0],
      "content" : {
        "en" : "THE SHAWSHANK REDEMPTION by Frank Darabont"
      },
      "meta" : {
        "property": "value"
      }
  },
  "meta": {
    "created" : "2004-02-12T15:19:21+00:00",
    "modified" : "2004-02-12T15:19:21+00:00"
  },
  "scenes" : [

  ],
  "status" : {
    "color": "blue",
    "round" : 1,
    "updated" : "2004-02-12T15:19:21+00:00",
    "meta" : {
      "property": "value"
    }
  },
  "styles": [
    {
      "id" : "courier-12",
      "default": true,
      "content" : "font-family: courier; font-size: 12px;",
      "meta" : {
        "property": "value"
      }
    }
  ],
  "templates": [
    "default"
  ]
}