Global Container

The Container parent object is the root of the entire screenplay which holds global data available to all objects and creates the environment for a Document. It is analogous to a file format in setting out the environment in which the script should be interpreted.

Attributes

The raw properties of a container are noticeably similar to HTML. A container is designed to set out a ScreenJSON document’s global definitions for everything and its meta properties, with the content enclosed in a child Document object.

The IDs (GUIDs) specified in each object are designed to be referenced elsewhere with any part of the content. For example, an Author entry with a unique UUID might be referenced in a Revision object in a Scene.

Individual Properties

A Container must include a character set, a unique ID which specifies the entire package (and its format), the language of the JSON, its creation locale, the titles of the work, and a Document object which holds the content. All other properties are optional.

Property Description Type Required
charset Character set the content was created in (e.g. utf8) string Yes
document A Document object with the content of the screenplay. object Yes
encryption An Encryption object describing the cryto protocol. object No
id A unique identifier for the global document. string Yes
lang ISO country identifier for the main language of the file (en). string Yes
license A License object specifying the copyright. object No
locale ISO identifier for the environment used to create the document (en-GB). string Yes
dir Language direction (ltr/rtl). string Yes
taggable Master index of all slug-formatted keywords in the entire document. array[string] No
title A Title object with the name of the work. object Yes
guid The ISO format of identifiers used in the document (rfc4122). string Yes

Collection Properties

A Container must include an array of one or more Author, and Revision objects. All other collections are optional.

Property Description Type Required
authors One or more Author objects. array Yes
colors One or more Color objects (for all content). array No
contributors One or more Contributor objects. array No
derivations One or more Derivation objects. array No
revisions A list of Revision objects. array Yes
registrations One or more Registration objects. array No

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.


Color

A Color is a human-understandable description of a color which the end-user’s presentation UI should use in its display in order to reproduce the same (e.g. HTML colour value).

{
  "title" : "blue",
  "rgb" : [0,0,255],
  "hex" : "#0000FF",
  "meta" : {
    "property": "value"
  }
}
Property Description Type Required
hex Friendly HTML-reference code of the color. string No
meta Arbitrary Meta object of custom properties. object No
rgb RGB reference numbers of the color. array [int 0-255] Yes
title A sluggable, human-understandable name for the color. string Yes

Contributor

A Contributor describes any third party who has contributed artistically to the content, such as an editor, director, or script doctor.

{
  "id": "8e0cd67f-f9da-46b8-98b9-16169893b439",
  "given" : "John",
  "family": "Doe",
  "roles" : ["doctor", "editor"],
  "meta" : {
    "property": "value"
  }
}
Property Description Type Required
family Last/family/surname name of the contributor. string Yes
given First/given name of the contributor. string Yes
id Unique identifier for the contributor. string Yes
meta Arbitrary Meta object of custom properties. object No
roles Sluggable list of system roles/groups the contributor belongs to. array [string] No

Note

A Contributor is defined as a person reviewing, augmenting, or enhancing content originated by an Author.


Derivation

A Derivation describes an original artistic work used as a source for the content.

{
    "id" : "3608b093-1280-4834-9ea4-d9d2b8d711a6",
    "type": "novella",
    "title": {
      "en": "Rita Hayworth and Shawshank Redemption"
    },
    "meta" : {
      "isbn": "978-0896214408",
      "comments" : "Based upon the story Rita Hayworth and Shawshank Redemption by Stephen King"
    }
}
Property Description Type Required
id Unique identifier for the contributor. string Yes
meta Arbitrary Meta object of custom properties. object No
title A Title object describing the original work. object Yes
type A sluggable, human-understandable name for the work genre/group. 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()).


License

A License describes of the copyright under which the content is protected and the means to check its provisions and/or limitations.

{
    "identifier": "CC-BY-NC-ND-4.0",
    "ref": "https://spdx.org/licenses/",
    "meta" : {
      "property": "value"
    }
}
Property Description Type Required
identifier Sluggable label of the copyright schema. string Yes
meta Arbitrary object of custom properties. object No
ref Internet reference for the full definition of the copyright terms. object Yes

Note

A valid license is any identifier from the SPDX list: https://spdx.org/licenses/


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

Registration

A Registration describes where the content has been officially submitted to for copyright protection.

{
  "authority": "WGA",
  "identifier" : "4847494058",
  "created" : "2004-02-12T15:19:21+00:00",
  "modified" : "2004-02-12T15:19:21+00:00",
  "meta" : {
    "property": "value"
  }
}
Property Description Type Required
created ISO 8601 timezone date the registration was made. string Yes
authority Sluggable label of registration provider/host. string Yes
identifier Sluggable label of registration ID. string Yes
meta Arbitrary Meta object of custom properties. object No
modified ISO 8601 timezone date the registration was last updated. string No
ref Internet reference for the full definition of the copyright terms. object Yes

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

Title

A Title describes the name of the artistic work in one or more languages.

{
  "en": "THE SHAWSHANK REDEMPTION",
  "es-mx": "Sueño de fuga"
}
Property Description Type Required
[lang] Name of the work in the file’s main language. string Yes
[iso] Name of the work in the iso language code specified. string No

Container Example

A blank container could be expressed as the following:

Example ScreenJSON container file with simplistic values
 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
{
  "id": "37bd3b1b-160a-4a65-bbf2-7c92d400fbc1",
  "guid" : "rfc4122",
  "title": {
    "en": "THE SHAWSHANK REDEMPTION",
    "es-mx": "Sueño de fuga"
  },
  "lang": "en",
  "locale" : "en-US",
  "charset" : "utf8",
  "dir" : "ltr",
  "authors": [
    {
      "id": "01979fca-6ac3-479e-9f33-d89498836eb1",
      "given" : "Frank",
      "family": "Darabont"
    }
  ],
  "colors": [
    {
      "title" : "blue",
      "rgb" : [0,0,255],
      "hex" : "#0000FF"
    }
  ],
  "contributors": [
    {
      "id": "8e0cd67f-f9da-46b8-98b9-16169893b439",
      "given" : "John",
      "family": "Doe",
      "roles" : ["doctor", "editor"]
    }
  ],
  "derivations": [
    {
      "id" : "3608b093-1280-4834-9ea4-d9d2b8d711a6",
      "type": "novella",
      "title": {
        "en" : "Rita Hayworth and Shawshank Redemption"
      },
      "meta" : {
        "isbn": "978-0896214408",
        "comments" : "Based upon the story Rita Hayworth and Shawshank Redemption by Stephen King"
      }
    }
  ],
  "document" : {

  },
  "encryption" : {
    "cipher" : "aes-256-ctr",
    "hash" : "sha256",
    "encoding" : "hex"
  },
  "license" : {
    "identifier": "CC-BY-NC-ND-4.0",
    "ref": "https://spdx.org/licenses/"
  },
  "registrations": [
    {
      "authority": "WGA",
      "identifier" : "4847494058",
      "created" : "2004-02-12T15:19:21+00:00",
      "modified" : "2004-02-12T15:19:21+00:00"
    }
  ],
  "revisions" : [
    {
      "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"
      }
    }
  ],
  "taggable" : [
    "first-keyword", "another-keyword"
  ]
}