Upload
others
View
4
Download
0
Embed Size (px)
Citation preview
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 1
MovieLabs Common Ontology JSON Schema
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 2
Creative Work JSON Schema Class Definitions ....................................................... 4
Top-level Objects..................................................................................................................................................................................................................... 4 System Identifier ..................................................................................................................................................................................................................... 5 Country .................................................................................................................................................................................................................................... 5 Language ................................................................................................................................................................................................................................. 6 Source...................................................................................................................................................................................................................................... 6 URL .......................................................................................................................................................................................................................................... 8 URI ........................................................................................................................................................................................................................................... 8 Date ......................................................................................................................................................................................................................................... 8 Note ......................................................................................................................................................................................................................................... 9 Identifier .................................................................................................................................................................................................................................. 9 Latitude and Longitude Coordinates ..................................................................................................................................................................................... 10 Location ................................................................................................................................................................................................................................. 10 Company ............................................................................................................................................................................................................................... 11 Date Start & End .................................................................................................................................................................................................................... 11 Time Period ........................................................................................................................................................................................................................... 11
Creative Work Class - JSON Schema ..................................................................... 13
Identifier ................................................................................................................................................................................................................................ 14 Referent Type ........................................................................................................................................................................................................................ 15 Adult ...................................................................................................................................................................................................................................... 16 Title........................................................................................................................................................................................................................................ 17 Release .................................................................................................................................................................................................................................. 19 Consumption ......................................................................................................................................................................................................................... 20 Original Language .................................................................................................................................................................................................................. 23 Associated Location .............................................................................................................................................................................................................. 24 Approximate Length .............................................................................................................................................................................................................. 25 Associated Companies .......................................................................................................................................................................................................... 26 Ratings ................................................................................................................................................................................................................................... 27 Rankings ................................................................................................................................................................................................................................ 28 Keywords ............................................................................................................................................................................................................................... 29 Based On ............................................................................................................................................................................................................................... 30 Cost ....................................................................................................................................................................................................................................... 31 Artwork ................................................................................................................................................................................................................................. 33
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 3
Contributors .......................................................................................................................................................................................................................... 34 Contributor Name ................................................................................................................................................................................................................. 37 Portrayal ................................................................................................................................................................................................................................ 37 Billing Order .......................................................................................................................................................................................................................... 38 Text ........................................................................................................................................................................................................................................ 39 Creative Work Summary ....................................................................................................................................................................................................... 40
Person Class - JSON Schema................................................................................. 41
Name ..................................................................................................................................................................................................................................... 42 Associated Locations ............................................................................................................................................................................................................. 43 Gender ................................................................................................................................................................................................................................... 44 Date of Birth or Death ........................................................................................................................................................................................................... 45 Star ........................................................................................................................................................................................................................................ 46 Person Summary ................................................................................................................................................................................................................... 47
Group Class – JSON Schema ................................................................................. 48
Group Elements..................................................................................................................................................................................................................... 49
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 4
Creative Work JSON Schema Class Definitions This first section details a set of base classes that align with the Common Ontology and are used throughout the schema.
Top-level Objects The ontology has several top-level object classes: Creative Work, Person, Location, Award, and Group. Top-level objects will always have an internal identifier (called ‘systemIdentifier’ in this schema), this can be used to connect them to other top-level objects. Not all of these must be implemented as separate objects in an underlying system. In this schema and its initial implementation:
• Creative Work: always a top-level object
• Location: The schema allows these to be top-level objects, but the initial implementation puts them in-line and not as independent objects.
• Person: Always a top-level object; a subset of the person data (name and id) is included in the Contributors field of a Creative Work.
• Groups: Always a top-level object.
• Award: currently not covered with a JSON schema.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 5
System Identifier This identifier is the internal identifier of the creative work in the underlying system. Examples include a database key for relational databases, a document name for a document store/no-SQL system, and an IRI for a system based on RDF. The id connects across top-level objects, e.g. films to people or franchises to films. This id is implementation specific, and typically attached to an instantiation of one of the top-level classes in an actual database.
Schema Name systemIdentifier
Field Name Requirement Control Type Description
systemIdentifier Optional String the internal ID for this object.
Country An ISO 3166-1 country code. This has been extended to include ‘WW’ for worldwide and some now defunct countries for historical content as per DOI and EIDR.
Schema Name country
Field Name Requirement Control Type Description
country enum String An ISO 3166-1 country code or accepted extension. Example: US – United States ES - Spain
Enumerated Field country.country
Enumerated values Description
ISO 3166-1 An ISO 3166-1 compliant country code, for example ‘US’ or ‘ES’, or accepted extension.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 6
Language Language codes are specified as per IETC RFC 5646, and allow for encoding of region specific variants. Refer to EIDR Language Code Best Practices http://eidr.org/documents/EIDR_Language_Code_Best_Practice_v1.6.pdf
Schema Name language
Field Name Requirement Control Type Description
language pattern String An ISO 639-1 or 639-3 language code, or language code with country of use Example: en – English es – Spanish es-MX – Spanish as spoken in Mexico zh-yue – Chinese Cantonese
Controlled Field language.language
Pattern
ISO 639-1/3 ^[a-z]{2}[a-z]?(-(([A-Z][A-Z])?|([a-z]{2}[a-z]?)))?$
Source All elements must have an attributable source which describes where the data for this element was obtained from, or the party responsible for creating it.
Schema Name source
Field Name Requirement Control Type Description
source Required String The source to which the data in this element is attributed to
Note: This field is not expressly enumerated but adhering to a list of recommended names for common sources of data is considered best practice. The following table provides a list of recommended terms for some common sources of creative works metadata.
source.type (this is not a controlled field but should comply where there is a corresponding type)
Suggested values Description
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 7
imdb Internet Movie Database (www.imdb.com)
eidr Entertainment Identifier Registry (www.eidr.org)
bfi British Film Institute (www.bfi.org.uk)
afi American Film Institute (www.afi.com)
dfi Danish Film Institute (www.dfi.dk/en)
sfi Swedish Film Institute www.filminstitutet.se/en/)
bomojo Box Office Mojo (boxofficemojo.com)
wikidata Wikidata (www.wikidata.org)
wikipedia Wikipedia (www.wikpedia.org)
lumiere European Audiovisual Observatory LUMIERE database (www.lumiere.avo.coe.int)
commonsensemedia Common Sense Media (www.commonsensemedia.org)
kinopoisk Kinopoisk (www.kinopoisk.ru)
rottentom Rotten Tomatoes (www.rottentomatoes.com)
flixster Flixster (www.flixster.com)
itunes iTunes (www.apple.com/itunes)
tmdb The Movie Database (www.themoviedatabase.com)
tcm Turner Classic Movies (www.tcm.com)
bluray Blu-Ray (www.blu-ray.com)
ondvd On DVD (www.ondvdreleases.com)
webedia Webedia uses a single id to identift content across a range of language specific site
allocine French site for the webedia group of sites (www.allocine.fr)
adoro Brazilian site for the webedia group of sites (www.adorocinema.com)
beyazperde Turkish site for the webedia group of sites (www.beyazperde.com)
filmstarts German site for the webedia group of sites (www.filmstarts.de)
sensacine Spanish site for the webedia group of sites (www.sensacine.com)
moviepilot German site for the webedia group of sites (www.moviepilot.de)
disney Internal Studio
fox Internal Studio
paramount Internal Studio
sony Internal Studio
universal Internal Studio
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 8
warner Internal Studio
Note: This is not an exhaustive list but includes examples for some of the more common seen sources and may be updated periodically.
URL A resolvable URL pointing to resource on which this source retains data pertaining to the record, or from which the data can be retrieved if it is not stored in the database, e.g. the full text of a review.
Schema Name url
Field Name Requirement Control Type Description
url Pattern String
Controlled Field url.url
Pattern
^(?:http(s)?://)?[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@%!\$&'\(\)\*\+\,;"=.]+$
URI A URI describing to a resource.
Schema Name uri
Field Name Requirement Control Type Description
uri Pattern String
Controlled Field uri.uri
Pattern
\w+:(/?/?)[^\s]+
Date An ISO 8601 compliant date or single year, this is typically associated with a release date, and does not include times or time-zones. It is in the format YYYY-MM-DD or YYYY.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 9
Schema Name date
Field Name Requirement Control Type Description
date Pattern String An ISO 8601 compliant date
Controlled Field date.date
Pattern
ISO 8601 (^(18|19|20)\d\d-(0\d|1[0-2])-[0-3]\d$)|(^(18|19|20)\d\d$)
Note A general-purpose field for placing comments or notes which do not have a prescribed field in other parts of the element. Other than being a string this field is never controlled or required.
Schema Name note
Field Name Requirement Control Type Description
note String Additional descriptive data about the element, that does not fit into one of the other fields.
Identifier A container for multiple types of identifiers that might apply to other creative works, locations, people, etc.
Schema Name identifier
Field Name Requirement Control Type Description
source Required $ref: source The source from which the identifier was obtained
id Required String The alphanumeric identifier
type Required String The organization or company that assigned and manages the identifier
url Optional $ref: url A URL that resolves to the primary source (web page, data connection, etc.) for the creative work at the managing organization for the identifier
domain Optional String Identifiers are valid for a particular domain. For standard identifiers e.g. EIDR, ISAN, etc.) a domain is not required – the identifier is assumed to be in the context of that standard. Some non-standard identifiers (e.g. IMDB) are de-facto standards, and so
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 10
do not need a domain. Most corporate or archival identifiers require a domain, often with a sub-domain for different classes of identifiers, e.g. bfi.org.uk and bfi.org.uk/gifford.
relation Optional Enum String The relation of the id to the creative work
Enum Field identifier.relation
Vocabulary Description
isSameAs This is equivalent to leaving the field ‘null’ and implies that the identifier is for the Creative Work to which it is attached.
deprecated This id has been deprecated and should no longer be used. Some systems (EIDR, IMDB) alias deprecated identifiers to newer or more correct ones, but this is not true for all systems. A deprecated identifier means that the identifier applied to the creative work at some point in the past, but no longer does so.
Latitude and Longitude Coordinates A container for coordinates of a location containing the longitude and latitude of that location.
Schema Name latLon
Field Name Requirement Control Type Description
longitude Required number The longitude of the location
latitude Required number The latitude of the location
Location A container for details about a specific location.
Schema Name location
Field Name Requirement Control Type Description
systemIdentifier Optional $ref: systemIdetifier If locations are kept as separate internal objects (their own Class), this is the key used to refer to this location. Otherwise it is optional to include it at all.
name Required String The name of the location
country Optional $ref: country The country the location is in
coords Optional $ref: latLon The longitude and latitude coordinates of the location
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 11
landmark Required Boolean Set true if this is considered a landmark Example: Eiffel Tower, White House
fictional Required Boolean Set true if this is a fictional location Example: Rivendell, Gotham City, Tatooine
identifiers Optional [$ref: identifier] An array of identifier objects for the location
note Optional Note Further notes regarding the location
Company A container for details about a company
Schema Name company
Field Name Requirement Control Type Description
name Required String The name of the Company
identifiers Optional [ $ref: identifier ] An array of external identifiers for the company
Date Start & End A container that allows a specific period of time to be defined using a start and end date. This record is often used to indicate a start date only where there is no defined end.
Schema Name dateStartEnd
Field Name Requirement Control Type Description
startDate Required $ref: date Starting date for period
endDate Optional $ref: date Ending date for period
Time Period A container for specifying a period of time using units of time and a count. This can be useful for things like box office, where revenue is often shown by week, or for a weekend. So, using a start date that began on a Friday, a time unit of days, and a time count of 3 you could describe a period that covered a weekend.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 12
Schema Name timePeriod
Field Name Requirement Control Type Description
startDate Required $ref: date Starting date for period
timeUnit Required Enum String The week within a set of time periods
timeCount Required Number The number of units of time covered in the record.
Example: With a timeUnit of Day, and timeCount of 3 this would indicate that the record refers to 3 days, inclusive of the startDate. The example below indicates Jan 1st, 2nd and 3rd. { startDate: 2019-1-1 timeUnit: ‘day’, timeCount: 3 }
Enum Field timePeriod.timeUnit
Enumerated values Description
day The unit of time is measured in days
week The unit of time is measured in weeks
month The unit of time is measured in months
year The unit of time is measured in years
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 13
Creative Work Class - JSON Schema The following describes each of the containers, or elements of the Creative Work class.
Schema Name CreativeWork
Field Name Requirement Type Description
systemIdentifier String A unique internal system identifier
identifiers [$ref: identifier] Array of identifier objects
referentTypes [$ref: referentType] Array of referentType objects
adult [$ref: adult] Array of adult objects
titles [$ref: title] Array of title objects
releases [$ref: release] Array of release objects
originalLanguages [$ref: originalLanguage] Array of originalLangauge objects
associatedLocations [$ref: associatedLocation] Array of associatedLocation objects
approximateLengths [$ref: approximateLength] Array of approximateLength objects
associatedCompanies [$ref: associatedCompany] Array of associatedCompany objects
ratings [$ref: rating] Array of rating objects
rankings [$ref: ranking] Array of ranking objects
keywords [$ref: keywords] Array of keyword objects
basedOn [$ref: basedOn] Array of basedOn objects
cost [$ref: cost] Array of cost objects
artwork [$ref: artwork] Array of artwork objects
contributors [$ref: contributor] Array of contributor objects
text [$ref: text] Array of text objects
releaseSummary $ref: releaseSummary releaseSummary object
Note: The systemIdentifier is the unique identifier used to identify the record within a specific database or implementation of this schema. As matter of practicality this will almost always exist, but there is not a necessarily a requirement, or desire, to expose this publicly, nor depending on the specifics of the underlying system does it have to be stored as part of the record itself.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 14
Identifier An identifier is a unique alphanumeric string that identifies the creative work within an external system. It may be public (EIDR, IMDB) or private (an internal studio identifier.) The identifier refers to the creative work; it may also apply to versions of the creative work, but that depends on the system that defines the identifier, e.g. an IMDB ID refers to all localized and censored versions of a film, but in EIDR edits and versions get separate IDs from the base creative work.
Schema Name CreativeWork.identifier
Field Name Requirement Control Type Description
source Required $ref: source Source of the identifier
identifier Required $ref: identifier Identifier sub-class (See above)
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 15
Referent Type Describes the ‘type’ of this creative work. These terms are fuzzy in both industry and archives (e.g. some sources do not distinguish TV and tvMovie).
Schema Name CreativeWork.referentType
Field Name Requirement Control Type Description
source Required $ref: source Source object
type Required Enum String The type of this work
Enum Field referentType.type
Enumerated values Description
movie A film typically made for theatrical release with a duration of 40 minutes or over
video The preferable term for a film released directly to the video home market, with a duration 40 minutes or over
tvMovie A non-episodic movie released first to the television or OTT market with duration of 40 minutes or over
tv An episodic or single episode work made for television or OTT broadcast
short A short film (less than 40 minutes, using the AMPAS definition)
Note: This list is currently limited due to this version of the ontology and schema only supporting movies, and not things like episodic television. This will be extended as necessary when additional content types are added.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 16
Adult A simple Boolean to indicate if the work is adult or pornographic in nature.
Schema Name CreativeWork.adult
Field Name Requirement Control Type Description
source Required $ref: source Source object
isAdult Required Boolean Set True when title is adult or pornographic, otherwise set False
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 17
Title Description of all known titles the work is referred by, including language and country when available
Schema Name CreativeWork.title
Field Name Requirement Control Type Description
source Required $ref: source Source object
title Required String The title
country Optional $ref: country Country object referencing the country in which the title is used
language Optional $ref: language Language object referencing the language of the title
type Optional Enum String A description of the kind of title
note Optional $ref: note Note object describing any additional attributes of the title
Enum Field type
Vocabulary Description
official An official name, often a translation used for international markets, but assigned by the originating studio or production company
original The main and typically first title, also usually that used in the country of origin
abbreviated Shortened version of the original, e.g. Harry Potter 7, for Harry Potter and the Deathly Hallows Part 1
acronym SATC for Sex & the City
fanBased A common name fans might use
working A name used typically during production before a formal name is given
internal A name or code name or nickname used internally
seriesNumeric Used when a work does not have an identifying name, but can be distinguished based on its season or episode numbers. For example: Season 2 Episode 3 of The Simpsons. Applies only to the primary title of Seasons and Episodes. Automatically generated.
seriesDate Used when a work does not have an identifying name, but can be distinguished based on its full release date (and optionally time slot). For example: The Evening News [2012-10-13]. Applies only to the primary title of Seasons and Episodes. Automatically generated.
regional Used for titles other than the original title in use within a specific region or country.
broadcast If a broadcast release has a different name
aka An alternative name that is often used to describe the film, Terminator 3: Rise of the Machines is often referred to as T3
fka Formerly known as
transliterated A transliterated version of the name, most commonly used for Romanized versions of titles from their original names.
display Various abbreviations or variants used for display in user interfaces
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 18
sort A name useful for sorting or searching, The Hangover is sorted as Hangover, The
piracy Often uses Leet or other obfuscation to alter a titles name making it harder to find for those not knowledgeable in the language, Avengers might be spelt Av3N93r2
other Used when no other type fits
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 19
Release Describes release dates for a creative work. A single object can contain a release date for different channels such as theatrical or home as well as specific distribution channels and format. Each release date can optionally carry consumption metrics both as a total amount or with more granular consumption data about a specific time period or periods.
Schema Name CreativeWork.release
Field Name Requirement Control Type Description
source Required $ref: source Source object
country Optional $ref: country Country object referring to the country of release
dates Required $ref: date Date object referring to the date of the release
distributor Optional $ref: company Details of the distributor in country
channel Optional Enum String The channel for distribution of this release
distribution Optional Enum String The type of distribution
format Optional Enum String The format of the release
consumption Optional [$ref: consumption] Array of consumption objects giving consumption details (see below)
note Optional $ref: note Additional notes or comments
Enum Field channel
Vocabulary Description
theatrical Released into theatrical distribution
home Released into the home market for sale or rental
broadcast Released via traditional broadcast over air or cable
piracy Released onto an illegal distribution channel associated with piracy
hospitality Airlines, hotels
Enum Field distribution
Vocabulary Channel Description
festival Theatrical A one time showing at a film festival
premiere Theatrical A film premiere, similar to festival and on occasion earlier than it’s limited or wide release
limited Theatrical A limited theatrical release
wide Theatrical A typical wide theatrical distribution
rerelease Theatrical A re-release of work that was out of distribution for some period
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 20
tvod Home Transactional Video on Demand – Purchase or rent on digital channel
svod Home Subscription Video on Demand – Subscription based viewing
pvod Home Premium Video on Demand – Typically early window rental
avod Home Advertising Video on Demand – Free to watch with advertising
disc Home Physical media, VHS, DVD, Blu-Ray
digital Home A broad form of digital release where the exact (xVOD is unknown), iTunes, Google Play, etc.
bitTorrent Piracy Form of peer to peer piracy
Enum Field format
Vocabulary Description
dvd Digital Video Disc
bluRay Blu-Ray disc
digital Digital distribution, no physical media
3d 3D version
iMax iMax version
70mm 70mm version
Consumption The consumption object contains specific consumption data about this a particular release. , Consumption is specific to a particular channel, distribution system and format, but may have multiple measures of consumption such as revenue, admissions, or the number of screens. The consumption container can contain smaller sub divisions of consumption. For example, the weekly totals for box office can be listed as separate sub-consumption elements nested within the total box office consumption element.
Schema Name CreativeWork.release.consumption
Field Name Requirement Control Type Description
source Required $ref: source Attributed source of data
timePeriod Optional $ref: timePeriod If not included then this will be inherited from the parent object
units Required Enum String Description of the units of measurement
currency Optional ISO 4217 Enum An ISO 4217 currency type where Currency is a unit
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 21
Example: usd – US Dollars eur - Euros
amount Required Number The total volume of associated consumption
subConsumption Optional [$ref: consumption]
Note: source, units, and currency can be omitted from subConsumption records, in which case they are assumed to be the same as in the parent consumption element.
Enum Field units
Vocabulary Description
currency The currency used (currency type must be specified in the currency field)
admissions The number of tickets sold
theatres Number of theatres a work is shown in
screens The number of screens a work is shown on
downloads The number of observed downloads
views The number of views for the work, can apply to forms of digital consumption like subscription, rental, or ownership
Enum Field currency
Vocabulary Description
ARS Argentinian peso
AUD Australian dollars
BRL Brazilian real
CAD Canadian dollar
CHF Swiss Franc
DKK Danish krone
EUR Euros
GBP Pound sterling
JPY Japanese Yen
NOK Norwegian krone
NZD New Zealand dollar
RUB Rubles
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 22
SEK Swedish krona
TWD New Taiwan dollar
USD US dollar
Note: This list encompasses a sub-selection of the ISO 4217 currency codes, those most likely to appear in the costs or revenue for creative works, and could be extended to include others
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 23
Original Language Describes the language or languages used in the original creative work. This does not include versions that may be sub-titled or dubbed for distribution in foreign territories.
Schema Name CreativeWork.originalLanguage
Field Name Requirement Control Type Description
source Required $ref: source Attributed source of data
language Required $ref: language A language that features in the original version of the film
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 24
Associated Location Locations that are associated with the creative work in some manner. This might include where the production company was located (often called country of origin in other systems), where the work was physically filmed, or where the narrative was set. This can include fictional locations as well real ones.
Schema Name CreativeWork.associatedLocation
Field Name Requirement Control Type Description
source Required $ref: source Source object
type Required Enum String The type of location
location Required $ref: location Location object
Enum Field type
Vocabulary Description
filming Parts or all of the creative work were film in this country
setting Parts or all of the creative work are set in this location. These can be fictional, for example The Shire in the Hobbit and Lord of the Rings.
production Production resources were based in this country
funding Funding for the creative work was received from individuals or governments in the country
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 25
Approximate Length The approximate running time for the creative work.
Schema Name CreativeWork.approximateLength
Field Name Requirement Control Type Description
source Required $ref: source Attributed source of data.
country Optional $ref: country The country with which this creative work is associated.
approximateLength Required ISO 8601 String The estimated duration or running length of the creative work formatted to the ISO 8601 duration format.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 26
Associated Companies Collection of companies associated with the production or distribution of the work
Schema Name CreativeWork.associatedCompany
Field Name Requirement Control Type Description
source Required $ref: source Source object
type Required Enum String It’s association with the work
company Required $ref: company The company details
Enum Field type
Vocabulary Description
producer The production company
distributor A distributor
broadcaster A broadcaster
copyright Copyright holders
studio The primary or originating studio for the work
editor Editing company
encoder Company responsible for encoding the work
postProduction A post production company
licensor Company offering a license to the work
other Any other company type that does not fit the above descriptions
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 27
Ratings The ratings applied to the creative work by a government or regulatory board, generally describing the suitability to an audience, for example the MPPA ratings system. See https://movielabs.com/md/ratings/ for a detailed list.
Schema Name CreativeWork.rating
Field Name Requirement Control Type Description
source Required $ref: source Attributed source of data
country Required $ref: country The country in which this rating was applies
rating Required String The rating itself
system Optional String The organization which applied the rating
uri Optional $ref: uri uri object
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 28
Rankings A ranking, or score, attributed to a creative work by a third party indicating a view as to its quality. This is typically data from websites or critics that rate or review movies and television.
Schema Name CreativeWork.ranking
Field Name Requirement Control Type Description
source Required $ref: source Source object
country Optional $ref: country Source object: The country to which this rank primarily applies to, or the country in which the source primarily operates.
rankSource Required String The original source of the rank, not necessarily where it was obtained from
rankDomain Optional String The domain for the rankSource
rankType Optional String The type of rank, typically users of the domain, or an aggregated rank from other sources
rank Required Enum Number The rank or score attributed to the creative work
votes Optional Number The number of votes cast to create this rank
lowScale Required Number The low end of the scale used in the ranking
highScale Required Number The high end of the scale used in the ranking. If this 1, and the lowScale is 0 the ranking is assumed to be binary (i.e. thumbs up or thumbs down)
Enum Field rankType
Vocabulary Description
user A ranking that is based on a sites users voting in some way.
critic A ranking from an individual critic or other review source such as a newspaper.
aggregated An ranking created from aggregating another set of ranks, most frequently done when combining multiple review scores to create an overall impression from multiple reviewers, such as Rotten Tomatoes.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 29
Keywords Keywords that can be associated with the work that provide a descriptive quality for the work.
Schema Name CreativeWork.keyword
Field Name Requirement Control Type Description
source Source Source object
value Required string The keyword
type Required Enum string A normalized description of the type of keyword
country Optional Country Country object
language Optional Language Language object
weight Optional Number A unit of measurement describing the importance of this genre or keyword compared to others of similar type.
lowScale Optional Number The low end of the scale used for the weight, e.g. 0 if a percentage scale, when using an ordinal scale this would be the highest weight used, so that priority run from 1 - n
highScale Optional Number The high end of the scale used for the weight, if using an ordinal scale this would be 1 (indicating the most important genre)
Enum Field type
Vocabulary Description
genre A description of the genre of the work
mood A description of the mood of the work
subject A description of the subject matter of the work
theme A description of themes present in the work
other Other descriptive terms or keywords
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 30
Based On A description of any other works that this work has been derived from or based on.
Schema Name CreativeWork.basedOn
Field Name Requirement Control Type Description
source $ref: source Source object.
name Required String The name of the work this is based on.
type Required Enum String A description of the type of work this is based on.
identifiers Optional [$ref: identifier] An array of external identifiers (identifiers has a field for URLs if appropriate).
note Optional $ref: note
Enum Field type
Vocabulary Description
book Based on book
comic Based on comic
graphicNovel Based on a graphic novel
person Based on a real person
character Based on a fictional character
play Based on play
musical Based on Musical
opera Based on an opera
song Based on a song
game Based on game
ride Based on theme park ride
film Based on a prior film (not necessarily a prequel)
tv Based on TV series or show
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 31
Cost Estimated costs associated with the work.
Schema Name CreativeWork.cost
Field Name Requirement Control Type Description
source Required $ref: source Source object
cost Required Number The estimated cost
currency Required ISO 4217 String ISO 4217 code representing the currency in which the cost is expressed
type Optional Enum String The type of cost described
Enum Field currency
Vocabulary Description
ARS Argentinian peso
AUD Australian dollars
BRL Brazilian real
CAD Canadian dollar
CHF Swiss Franc
DKK Danish krone
EUR Euros
GBP Pound sterling
JPY Japanese Yen
NOK Norwegian krone
NZD New Zealand dollar
RUB Rubles
SEK Swedish krona
TWD New Taiwan dollar
USD US dollar
Note: This list encompasses a sub-selection of the ISO 4217 currency codes, those most likely to appear in the costs or revenue for creative works, and could be extended to include others
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 32
Enum Field type
Vocabulary Description
production Costs attributed to producing the work
marketing Costs attributed to marketing the work
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 33
Artwork A container that can contain references to artwork related to the creative work.
Schema Name CreativeWork.artwork
Field Name Requirement Control Type Description
source Required $ref: source Source object
country Optional $ref: country Country object
url Required $ref: url A resolvable URL referencing the artwork in the element
width Optional Number Width of the image in pixels
height Optional Number Height of the image in pixels
type Optional Enum String The type of artwork
Enum Field type
Vocabulary Description
poster Used as promotional poster in billboards, theatres etc.
cover Used in packing of physical goods like Blu-Ray or DVD
promotional Used in promotional material
marketing Used in ancillary marketing material
fan Created by unofficial external sources, typically fans
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 34
Contributors The contributor container contains details of individuals associated with creation and staring in the creative work. The role name and department names are based on the EBU roles, codes and departments: https://www.ebu.ch/metadata/cs/web/ebu_RoleCodeCS_p.xml.htm. The enumerated lists below are a subset of the roles available with a focus on those most likely to be nominated for industry awards. Type (talent or crew) is the coarsest distinction, followed by department, followed by the role(job) played in the production. There is a companion document ‘role-map-v1.0.xlsx’, that provides mappings across vocabulary sets from several sources and FIAF, EBU, RDF, JSON types. The following two links reference the EBU codes and FIAF roles https://www.ebu.ch/metadata/cs/web/ebu_RoleCodeCS_p.xml.htm https://www.fiafnet.org/pages/E-Resources/Glossary.html#
Schema Name CreativeWork.contributor
Field Name Requirement Control Type Description
source Required Source Source object
systemIdentifier Optional String The internal identifier referencing the Person class for this individual
role Optional Enum String The specific role (job) held in the production of the work, see reference document for full details
department Optional Enum String The department this job role belongs to
type Optional Enum String Designation as to whether this role is cast or crew, this more simplistic designation of the role is useful for certain search patterns
contribName Required $ref: contribName Contributor Name object (see below)
portrayal Optional [$ref: portrayal] An array of Portrayal objects (see below)
billing Optional [$ref: billing] An array of Billing objects (see below)
Enum Field CreativeWork.contributor.role
Field Value Description
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 35
productionDesigner Production Designer, responsible for overall visual appearance of work including sets, props and costumes
artDirector Art Director, provides oversight of set design and construction
setDesigner Set Designer, responsible for design & dressing of the sets (furniture, lighting fixtures, etc.)
sfxSupervisor Special Effects Supervisor, responsible for creating artificial effects on set such as bullet holes, explosions, etc.
dirOfPhotography Director of Photography
castingDirector Casting Director
editor Film Editor
dialogueEditor Dialogue editor
soundEditor Sound Editor
soundMixer Sound Mixer
hair Hairdressing and Wigs
makeup Makeup & Prosthetics
lyrics Lyricist
composer Composer of film score or music
songComposer Composer of specific audio tracks or songs within the work
producer The Producer of the work
execProducer The Executive Producer of the work
director The director of the work
assitantDirector The Assistant Director of the work
writer Writer or screenwriter of the work
authorOfSource Author of original source material, such as book
stuntCoordinator A stunt coordinator
stuntActor Stunt actor
actor Actor of any gender designation
voiceActor A voice actor of any gender designation
self An individual who portrays themselves in a work
choreographer The choreographer
dubbingActor A dubbing or voice over actor of any gender designation
vfxSupervisor Visual Effects Supervisor
costumeDesigner Costume designer
archive Person who oversees or manages archival audio or visual content
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 36
Note: The roles in the table above are based broadly on the EBU and FAIF role definitions. This limited set is designed to cover roles that are typically nominated for awards and roles that might be of interest for search and recommendation. See the document mentioned above for details.
Enum Field CreativeWork.contributor.department
Field Value Description
accounting Accounting Department
aerialSupport Aerial Support and Services
animal Animal Department
animation Animation Department
art Art Department
camera Camera Department
casting Casting Department
catering Catering Department
consultant Consultants / Experts
distribution Distribution
editingMontage Editing / Montage
grip Grip Department
makeupWig Hair & Makeup / Wig Department
it IT Department and Services
lightingElectrical Lighting / Electrical
marine Marine
music Music Department
news News Department
postProduction Post-Production
production Production
promotion Promotion
script Script Department
sound Sound Department
stunts Stunts Department
talent Talent
transportation Transportation Department
vfx Visual Effect Department
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 37
wardrobe Wardrobe Department
otherCrew Other Crew Roles
outsideBroadcast Outside Broadcast Crew
trainersCoaches Trainers / Coaches
translationDubbing Translation / Dubbing / Captioning / Signing
medical Medical Crew
project Project
martialArts Martial Arts / Fighting
Enum Field CreativeWork.contributor.type
Field Value Description
talent An individual with an onscreen or acting role in the film, would include voiceovers and narration, etc.
crew An individual involved with the production of the film.
Contributor Name The name of the Person who contributed to this creative work.
Schema Name CreativeWork.contributor.contribName
Field Name Requirement Control Type Description
source Required $ref: source Source object
name Required String The name of the person as used by the referenced source
Portrayal A container for a single instance of an actor and a character they play in the work. Characters that play multiple characters can have multiple portrayals, or could have separate contributor records.
Schema Name CreativeWork.contributor.portrayal
Field Name Requirement Control Type Description
source Required $ref: source Source object
actor Required String The name of the person playing this character, per this source
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 38
character Required String The character name in the creative work, per this source
Billing Order A container for describing the contributors place in the billing order.
Schema Name CreativeWork.contributor.billingOrder
Field Name Requirement Control Type Description
source Required $ref: source Source object
name Required String The name of the person as referred to by this source
billingOrder Optional Number The numerical sequence in which the cast or crew is listed by this source in the credits
billedRole Optional String The billed role as described in the original source, use to preserve the original role as some sources use screen billing, others their own language.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 39
Text A container for holding any sort of text associated with the work. This can include things like a synopsis, reviews or other descriptive text that goes beyond keywords.
Schema Name CreativeWork.text
Field Name Requirement Control Type Description
source Required $ref: source Source object
type Required Enum String The type of text
country Optional $ref: country The country from which the text referred to in the element originates from
language Optional $ref: language Language object, the language this text is written in
url Optional $ref: url A URL referencing the original text in the element
date Optional $ref: date The date the text was first published
text Required String The body of the text
Enum Field type
Vocabulary Description
synopsis A synopsis
copyright A copyright line often used by distributers
tagline A short, one sentence, line used to describe the work
review A third-party review
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 40
Creative Work Summary The Creative Work summary is optional and primarily included as a way of maintaining some key data points about the work, often useful in for creating search indexes in databases, or for quick retrieval and providing summary data to applications. It is likely that some or all these fields will be selected or computed based on a set of decisions driven by a specific application or need. The source is to indicate which organization was responsible for generating this record and does not relate to the data itself. The data itself may well be generated, or possibly duplicated across more than one original source. The types are left to the discretion of the system implementer, they could be a single primitive value (string or number), an array of primitives or an appropriate object as per the schema definition, i.e. for actors either a single name could be used, or the contributor object which would include portrayal and billing.
Schema Name CreativeWork. summary
Field Name Requirement Control Type Description
source Required $ref: source Source of this release summary.
identifiers A single, or list of identifiers.
releaseYear The year of the first known release.
theatricalRelease The date of the first known theatrical release.
homeRelease The date of the first known home release.
broadcastRelease The date of the first known broadcast release.
title A single primary title, or array of the main titles
rating The films rating
votes (ranking) The number of votes received from a voting system or systems
studio A primary studio behind the work
director A single director, or an array if more than one
cast A list of the main actors, or stars in the work
artwork A reference to artwork
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 41
Person Class - JSON Schema The Person class describes an individual and includes all details about that person likely to be relevant to media content A subset of the information is included as part of a contributor record in the CreativeWork class; from which the full information can be recovered by resolving the id in the contributor. The Person Class in this version 1.0, has been deliberately defined as to be light on detail. Defining people can become quite a complex task, even apparently simple things like a person’s first, last and middle names can get quite complicated; when they change names, when they don’t use them, when they have hyphenated surnames, multiple middle names, etc. We anticipate extending the Person class in the future to deal with some of these more complex issues but feel more discussion and input from industry sources is worthwhile before deciding on a final ontology.
Schema Name Person
Field Name Requirement Control Type Description
systemIdentifier Required String The internal id of this person
identifiers Optional [$ref: identifier] An array of identifier objects for the person
names Optional [$ref: Person.name] An array of name objects (see below)
associatedLocations Optional [$ref: associatedLocation] Locations associated with the person, for example place of birth (See below).
gender Optional [$ref: Person.gender] Description of person identified gender (see below)
dateOfBirth Optional [$ref: Person.dateOf] Persons date of birth (see below)
dateOfDeath Optional [$ref: Person.dateOf] Persons date of death (see below)
seenAsStar Optional [$ref: Person.star] Indicates if person is considered ‘a star’ (see below)
contributedTo Optional [$ref: CreativeWorks.summary] List of works the person contributed to; the underlying system may provide filters for this when querying/resolving a person record
summary Optional $ref:Person.summary A summary of the Person record
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 42
Name A container used to describe a person’s name as defined by the source. This also includes the type of name, given that people sometimes use multiple names or variations of their names such as pseudonyms. As noted above, this version of the schema does not split names into given name/family name, first name/last name, etc. We have not specified the order the person’s name; however, we suggest best practice to be first last.
Schema Name Person.name
Field Name Requirement Control Type Description
source Required $ref: source Source object
name Required String The person’s name as found in the source
language Optional $ref: language Language object, describing language name is written in
type Optional Enum String The type of name
Enum Field Person.name.type
Enumerated values Description
birthName A person’s given name at birth, a therefore preceding any later name changes
primaryName The name primarily used by the person for credit in work
pseudonym A fictitious name
alternateName An alternate name, Also Known As (AKA)
translatedName A translated name, often a ‘western name’, used by an Asian actor
nickname An often humorous or familiar name, often given to someone by friends.
moniker A personal name, similar to a nickname, a name someone often goes by
alias A false or assumed name, often one the person is better known as
contractualName A name used contractually, which may differ from any of the above
displayName A name used for display purposes
sortName A name used in sorting, often ‘last, first’
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 43
Associated Locations A container for holding locations that are relevant to this Person, such as their place of birth or death. This uses the location object so could include a country, city or other form of location.
Schema Name Person.associatedLocation
Field Name Requirement Control Type Description
source Required $ref: source Source object
location Required $ref: location Location object
type Optional Enum String The type of name
Enum Field Person.associatedLocation.type
Enumerated values Description
placeOfBirth Where the person was born
placeOfDeath Where the person died
countryOfCitizenship Country of citizenship
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 44
Gender A container for encoding a person’s gender. That is, how a person publicly identifies themselves, not necessarily how others in society might view them.
• Sexual orientation is not included/encoded.
• Gender expression (e.g., gender-specific clothing, hair length, or makeup) is not included/encoded.
• Sexual reassignment status is not included/encoded.
Schema Name Person.gender
Field Name Requirement Control Type Description
source Required Source Attributed source of data
gender Required Enum String The person’s gender as found in the source.
specificGender Optional [String] Uncontrolled field to accommodate the variations of self-identified gender.
transgender Optional Boolean If true, this indicates a person is transgender.
Enum Field Person.gender.gender
Enumerated values Description
male Identifies as male
female Identifies as female
other Anything that doesn’t fit the other three.
neutral Entities where gender doesn’t apply, e.g. some robots. This will generally not be used for a person but could be used when characters have no gender.
As an example, Richard O’Brien (“The Rocky Horror Picture Show” and “Phineas and Ferb”) is listed in Wikidata as ‘non-binary.’ This would be encoded as: {
source: “wikidata”, gender: “other”, specificGender: [“non-binary”], transgender: true,
}
If the person is trans-gender and the self-identified gender is male or female, the specificGender field does not have to be populated.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 45
Date of Birth or Death A container for holding the date of an event related to the person, such as their date of birth or death.
Schema Name Person.dateOf
Field Name Requirement Control Type Description
source Required $ref: source Source object
date Required $ref: date Date object
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 46
Star This indicates that a particular source views the person as ‘a star’. For example, both IMDB and the AFI have such lists.
Schema Name StarWithSource
Field Name Requirement Control Type Description
source Required $ref: source Attributed source of data
star Required Boolean True if the source considers this person a star.
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 47
Person Summary The Person summary is an optional field that contains consolidated information from the Person record. Given that any record may have multiple options to choose from, i.e. multiple names of different types or from different sources, this provides a container for a instantiation to make a decision as to which information is most relevant. This can be useful in creating search indexes within a database, or as a means of quick retrieval of some basic information to an application. The fields below are suggested, but others can be substituted.
Schema Name Person.summary
Field Name Requirement Control Type Description
systemIdentifier Required String The internal id of this person
identifiers String or Array A secondary identifier or list of identifiers for external systems
preferredName String The name by which the person is commonly known
dateOfBirth $ref: date Date of birth
dateOfDeath $ref: date Date of Death
gender $ref: Person.gender The persons gender
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 48
Group Class – JSON Schema Groups provide a simple mechanism for collecting Creative Works into a defined set. Groups can have a predefined type, such as brand or franchise, or can be ad-hoc, which indicates an arbitrary set (e.g. for purposes of marketing or analysis.)
Schema Name Group
Field Name Requirement Control Type Description
systemIdentifier Optional String The internal identifier of the group
type Required Enum String The type of the group
source Required $ref: source Source object
name Required String The name of the Group
identifiers Optional [$ref: identifier] External identifiers for the Group, for including groups from third party sources
description Optional String A short description of the Group (preferably single word)
members Required [$ref: groupElement] The creative works in the Group (see below)
isOfficial Optional Boolean True if the group has some official status
Note Optional $ref: note Other information that isn’t included in the description
Enum Field Group.type
Enumerated values Description
brand
universe
franchise
character
adHoc
sales
display
MovieLabs Common Ontology – JSON Schema Open Distribution
Ver: 1.0.0 Date : 5/30/19
Motion Picture Laboratories, Inc. 49
Group Elements A container for describing the creative works in the group
Schema Name Group.groupElement
Field Name Requirement Control Type Description
source Required Source Attributed source of data
systemIdentifier Required String Internal ID for the creative work
identifiers [$ref: identifier] External identifiers for creative works in group
titleSummary Optional [$ref: CreativeWorks.summary] For convenience; can be retrieved using the Creative Work’s id.
note Optional $ref: note Any other information, e.g. why this Creative Work is in the Group.