Element

An Element is a piece of a scene such as dialogue or action, and analogous to a paragraph in an editing program. It contains the content of the work.

Any element can invoke multiple sets of styling, and accomodate language equivalents, as well as revisions and annotations (defined by their start and end character indexes in the string).

Warning

Access policies are a list of policy identifiers known to the host application, which is responsible for managing and implementing them.

The purpose of an Element object is to define the following information:

  • Technological implementation data (CGI, 3D etc)
  • Access & UI display policy
  • Multi-lingual content equivalence
  • Revision-tracking & annotations

Types

An Element object can have a type of:

  • action
  • character
  • dialogue
  • general
  • parenthetical
  • shot
  • transition

Note

Dual-dialogue is an attribute dual: true of an element with a ‘type’ property of dialogue.

Note

Dialogue direction data (e.g. V.O, O.S) should be specified in an element a ‘type’ property of dialogue using the property origin.

Note

The interactivity attribute is reserved for future versions.

Attributes

An Element would be a paragraph in a word-processing program, and typically defined by its visual presentation on the page. ScreenJSON describes the data inside the element but does not care how it is displayed - which is a task for the GUI host processing the file.

Individual Properties

An Element must have a type, define its charset, language direction, link its parent element and scene, and contain content.

Property Description Type Required
access A sluggable list of role groups permitted to view the element content. array[string] No
authors A list of author IDs array[string] Yes
charset Character set the content was created in (e.g. utf8) string Yes
class A visual presentation class to apply to the content. string No
content A Content object with the text. object Yes
contributors A list of contributor IDs array[string] No
dir Language direction (ltr/rtl). string Yes
dom A comparative reference to a parallel XML/HTML tag/element. string No
dual Whether or not the element contains dual dialogue. boolean No
encryption An Encryption object with decrypt info. object No
fov The inferred field of view of the camera (e.g. 360 degrees) string No
id Unique identifier for the element. string Yes
interactivity Whether or not the element contains interactive elements or triggers. boolean No
locked Whether or not the element is locked for editing/revision. boolean Np
meta An arbitrary Meta object of custom values. object No
omitted Whether or not the element should be omitted from display. boolean No
origin Where the dialogue originates: V.O, O.S, O.C, FILTER. string No
parent Identifer of the parent element (e.g. dialogue –> character). string Yes
perspective The inferred visual perspective of the element(e.g. 2D/3D) string No
scene Identifer of the parent scene. string Yes
styles A sluggable list of style identifiers for displaying the content. array[string] No
type The type of element: action, character, dialogue, parenthetical etc. string Yes

Collection Properties

An Element must include an array of revisions. All other collections are optional.

Property Description Type Required
annotations One or more Annotation objects. array No
revisions One or more Revision objects. array Yes

Note

An Author is defined as someone who writes the content of the screenplay. A Contributor is someone who comments or augments it.

Sub-Objects

Author

An Author describes an original writer of the content.

{
  "id": "01979fca-6ac3-479e-9f33-d89498836eb1",
  "given" : "Frank",
  "family": "Darabont",
  "meta" : {
    "property": "value"
  }
}
Property Description Type Required
family Last/family/surname name of the author. string Yes
given First/given name of the author. string Yes
id Unique identifier for the author. string Yes
meta Arbitrary Meta object of custom properties. object No

Note

An Author is defined as the originator of the content which has being written, which may be reviewed or augmented by a Contributor.

Annotation

An Annotation is a metadata item which describes an ancillary note made on an object.

{
  "id": "8537e8d6-758c-439c-af10-f60dd693044a",
  "parent" : "9db20a5b-cece-45be-96a0-c31ecedb721a",
  "highlight": [
    [3,6],
    [7,9]
  ],
  "contributor": "8e0cd67f-f9da-46b8-98b9-16169893b439",
  "created" : "2004-02-12T15:19:21+00:00",
  "content" : {
    "en" : "Does it have to be dark?"
  },
  "color" : "blue",
  "meta" : {
    "property": "value"
  }
}
Property Description Type Required  
color Label of a Color object specifying what colour to display. string No
content A Content object with the text of the note. object Yes
contributor The ID of the Author or Contributor who wrote the text. string Yes
created ISO 8601 timezone date the note was made. string Yes
highlight String character sequences to visually highlight (first/last chars). array[int] No
id Unique identifier for the annotation. string Yes
meta Arbitrary object of custom properties. object No
parent Parent identifier of the object being annotated. string Yes

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

Encryption

Encryption describes the means (protocol, cipher etc) used to encrypt the content. Its purpose to enable the end-user’s presentation UI to quickly recognise the data and load the appropriate libraries required to decode the content when the appropriate credentials are supplied.

{
    "cipher" : "aes-256-ctr",
    "hash" : "sha256",
    "encoding" : "hex",
    "meta" : {
      "property": "value"
    }
}
Property Description Type Required
cipher Cipher the content is encrypted with. string Yes
encoding Type of encoding used for the output. object Yes
hash Hash type the content is encrypted with. string Yes
meta Arbitrary Meta object of custom properties. object No

Note

Valid ciphers and hashes are derived from cryptojs using console.log(require(‘crypto’).getCiphers()).

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

Revision

A Revision describes when a parent container or sub-section of content was changed.

{
  "id": "8537e8d6-758c-439c-af10-f60dd693044a",
  "parent" : "9db20a5b-cece-45be-96a0-c31ecedb721a",
  "index": 0,
  "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
  "version": "draft",
  "created" : "2004-02-12T15:19:21+00:00",
  "meta" : {
    "property": "value"
  }
}
Property Description Type Required
authors List of author IDs who created the revision. array[string] Yes
created ISO 8601 timezone date the revision was recorded. string Yes
index Internal index of the revision. int Yes
meta Arbitrary Meta object of custom properties. object No
parent Parent identifier of the object being revised. string Yes
version Human-readable type of revision. string No

Single Element Example

A small sequence of 1 action line could be expressed as the following:

Example ScreenJSON scene of a single element (first line of a script)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
  "id": "832a4322-c2e7-4e42-b049-e6f9c821f7f0",
  "parent" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
  "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
  "access" : ["ABL", "cast", "cinematography", "locations", "wardrobe", "vfx", "sfx"],
  "annotations" : [
    {
      "highlight": [
        [3,6],
        [7,9]
      ],
      "contributor": "8e0cd67f-f9da-46b8-98b9-16169893b439",
      "created" : "2004-02-12T15:19:21+00:00",
      "content" : {
        "en" : "Does it have to be dark?"
      },
      "meta" : {
        "property": "value"
      }
    }
  ],
  "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
  "charset" : "utf8",
  "class": "col-md-12",
  "content" : {
    "en" : "A dark, empty room."
  },
  "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
  "dir" : "ltr",
  "dom": "p",
  "encryption" : {
    "cipher" : "aes-256-ctr",
    "encoding" : "hex",
    "meta" : {
      "property": "value"
    }
  },
  "fov" : "360",
  "id" : "34dd2b5a-4d57-4379-9cd2-e77b5d2ffbaa",
  "interactivity" : false,
  "locked": false,
  "meta" : {
    "property": "value"
  },
  "omitted": false,
  "perspective" : "2D",
  "revisions" : [
    {
      "index": 0,
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "version": "draft",
      "created" : "2004-02-12T15:19:21+00:00",
      "meta" : {
        "property": "value"
      }
    }
  ],
  "styles" : [
    "default"
  ],
  "type": "action"
}

Multi-Element Example

A small sequence of 2 characters saying hello to each other could be expressed as the following:

Example ScreenJSON scene of 2 characters as a “Hello, World” sequence
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{
  "body": [
    {
      "id": "832a4322-c2e7-4e42-b049-e6f9c821f7f0",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "action",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "Bob and Alice sit facing each other."
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "revisions": [
        {
          "id" : "b1fba741-4870-44fe-9b7d-234e8f0f5e5f",
          "parent": "832a4322-c2e7-4e42-b049-e6f9c821f7f0",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    },
    {
      "id" : "54cad943-a74b-44b7-b4f3-c3168d57840d",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "character",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "BOB"
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "origin" : "O.C",
      "revisions": [
        {
          "id" : "92dc6154-3a82-408d-83e6-fd4573eefbef",
          "parent" : "54cad943-a74b-44b7-b4f3-c3168d57840d",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    },
    {
      "id": "dee1e326-9325-40a2-a7df-9d51dc5526ec",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "54cad943-a74b-44b7-b4f3-c3168d57840d",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "dialogue",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "Hi, Alice."
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "revisions": [
        {
          "id" : "eda2da50-c81b-4e93-bd79-68cd5f8fa8e1",
          "parent" : "dee1e326-9325-40a2-a7df-9d51dc5526ec",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    },
    {
      "id": "81fcebe1-a2ae-4d49-91ac-b544d9a7cad6",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "character",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "ALICE"
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "dir": "ltr",
      "revisions": [
        {
          "id" : "e024278d-cb33-4228-92d4-eb08cc180fb3",
          "parent" : "81fcebe1-a2ae-4d49-91ac-b544d9a7cad6",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    },
    {
      "id" : "6e27748b-b5d9-4da5-8e53-c2766a1c074b",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "81fcebe1-a2ae-4d49-91ac-b544d9a7cad6",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "dialogue",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "Hi, Bob!"
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "revisions": [
        {
          "id": "c34bc1a7-fa99-4e3c-8d91-14498cdae5c0",
          "parent" : "6e27748b-b5d9-4da5-8e53-c2766a1c074b",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    },
    {
      "id" : "c776c8e9-4549-4552-a68b-8bcc013c1884",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "81fcebe1-a2ae-4d49-91ac-b544d9a7cad6",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "parenthetical",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "Leaning in, smiling broadly"
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "revisions": [
        {
          "id" : "72194545-f6cd-44ae-b713-11067d9efaf8",
          "parent" : "c776c8e9-4549-4552-a68b-8bcc013c1884",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    },
    {
      "id" : "9d2cd285-f523-40ca-b587-cd156a68fe6d",
      "authors" : ["01979fca-6ac3-479e-9f33-d89498836eb1"],
      "parent" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "scene" : "271ee0f5-8ce8-46e6-919f-87b9ace58496",
      "type": "action",
      "charset": "utf8",
      "dir": "ltr",
      "content": {
        "en": "Bob hands her flowers."
      },
      "contributors" : ["8e0cd67f-f9da-46b8-98b9-16169893b439"],
      "revisions": [
        {
          "id" : "e5acb0ed-a901-4c7e-8ee5-ee57f53ef7a9",
          "parent" : "9d2cd285-f523-40ca-b587-cd156a68fe6d",
          "index": 0,
          "authors": [
            "01979fca-6ac3-479e-9f33-d89498836eb1"
          ],
          "version": "draft",
          "created": "2004-02-12T15:19:21+00:00"
        }
      ]
    }
  ]
}