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¶

{
  "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"
  ]
}