Resource datamodel:asset-model

Overview

The datamodel:asset-model resource represents the data model of an asset or asset type.

Properties

The datamodel:asset-model resource has the following properties:

attributes

Definition of common and custom attributes that the asset can have.

time-based

Definition of the layers of time-based annotation that the asset can have.

layout

Definitions of recommended Metadata layouts. Sub properties:

  • attributeGroupLayout: a layout based on groups of attributes

  • simpleTimeBasedLayout: a simple layout for time-based annotation

  • virtualLayersLayout: allow to express combinations of layers having specific semantics

Link Relations

The datamodel:asset-model resource has no link relations.

Description

The datamodel:asset-model resource represents the data model of an asset or asset type.

This includes information about the available attributes and layout information for use in Graphical User Interfaces.

Example:

{
    "attributes":{
        "common":[
            // description of common attributes
        ],
        "custom":[
            // description of custom attributes
        ]
    },
    "time-based":[
        // description of the layers of the time-based annotation
    ],
    "layout":{
        "attributeGroupLayout":[

        ],
        "simpleTimeBasedLayout":[

        ],
        "virtualLayersLayout":[

        ]
    }
}

attributes

The property attributes contains information about the attributes used for an asset or an asset type. It contains two sub properties:

  • common: description of the common attributes. The values of the common attributes are returned in the property common of aa:asset

  • custom: description of additional, custom attributes that are valid for this specific asset. The values of the custom attributes are returned in the aa:attributes sub resource of aa:asset.

Both sub properties contain an array of attribute descriptions. The structure is similar to the attribute description in datamodel:aggregated-model, but with the following differences:

  • appliesTo: is not present, because we are in the context of an aa:asset

  • flags contains the flags for this specific asset (or asset type) and for the calling user. Example: an attribute may come without "readonly" flag in datamodel:aggregated-model because the attribute can be edited for some asset, but here it is "readonly", because the user is not allowed to edit the attribute for this specific asset.

An attribute definition has the following properties:

Property

Description

id

Identifier of the attribute. For common attributes, it is the same as the property name used in the common representation, e.g. "startTC", "name", or "description".

type

Defines the type of the attribute. The structure is similar to the structure in datamodel:system-model for details.

flags

(Optional) An array of flags for the attribute. Currently, the following flags have a defined meaning:

  • readonly: attribute should be displayed as read-only attribute

  • indexed: attribute is searchable.

  • mandatory: attribute is mandatory, meaning that is must have a non-empty value.

  • editor: !!Subject to change in future versions!! (Specific for MediaCentral Production Management, should not be used for other services) the attribute is enabled for editing in attribute editing applications.

Other flags may be added in the future.

description

(Optional) A description of the attribute. This is only used for human users of the API.

labels

(Optional) Contains a mapping of culture codes to localized labels. Example:

{
    "en-US": "Aluminum",
    "en-UK": "Aluminium",
    "en": "Aluminium",
    "de": "Aluminium"
}

Typically, the client asks for the labels for the language of the user using a query parameter like, for example, lang=fr-CA (for Canadian French). In this case, the service cares about a proper fallback mechanism (e.g. using the label for "fr", if no specific label for "fr-CA" is available). If the client doesn’t request a specific culture, it should implement a similar language fallback mechanism to find the correct label.

tooltips

(Optional) Defines localized tool tips for the attribute. The structure is similar to the one for labels.

subattributes

(Optional) An array of sub-attributes of the attribute, e.g. to represent a MVC-attribute in MediaCentral Asset Management. The structure of subattributes' elements is equivalent to those of attributes.

Example for an attribute description 
 
{
    "id":"name",
    "description":"display name",
    "labels":{
        "en":"Name",
        "de":"Name"
    },
    "tooltips":{
        "en":"Name",
        "de":"Name"
    },
    "type":{
        "baseType":"string",
        "maxLength":256,
        "multiValue":false
    },
    "flags":[
        "indexed",
        "readonly"
    ],
    "subattributes":[
        {
            "id":"subattribute1 name",
            "labels":{
                "en":"subattribute1 en label"
            },
            "tooltips":{
                "en":"subattribute1 en tooltip"
            },
            "type":{
                "baseType":"string",
                "maxLength":256
            }
        },
        {
            "id":"subattribute2 name",
            "labels":{
                "en":"subattribute2 en label"
            },
            "tooltips":{
                "en":"subattribute2 en tooltip"
            },
            "type":{
                "baseType":"string"
            }
        }
    ]
}

time-based

The property time-based defines the details of the time-based annotation capabilities for the asset.

The information in this property is not about the actual segments of the assets. To get that information you must follow the aa:time-based link in the aa:asset resource. This property returns information about the available attributes, their types and how to deal with them.

The property time-based contains an array of layer definitions. Each layer is defined with the following properties:

Property

Description

id

Identifier of the layer. This is the same identifier that is returned when querying the actual segments of the asset.

description

A human-readable description for the layer.

labels

Localized display labels for the layer. The structure is the same as for the labels of attributes.

tooltips

Localized tooltips for the layer. The structure is the same as for the tooltips of attributes.

ranged

A boolean value. If true, the segments can span multiple frames. If false, segments are always assigned to a single frame ("marker").

  • MediaCentral Production Management: defaults to true for restrictions, defaults to false for tracks

  • MediaCentral Asset Management: defaults to true

gaps

A boolean value. If true, then there can be gaps between segments, meaning: time ranges without segments. If false, then there must be a continuous sequence of segments and no time range without at least one segment assigned to it.

  • MediaCentral Production Management: defaults to true

  • MediaCentral Asset Management: depends on profile "Cataloger", setting "Settings/AllowGapsInStrata" and otherwise defaults to true

overlap

A boolean value. If true, then segments can overlap other segments. If false, then segments can’t overlap other segments.

  • MediaCentral Production Management: defaults to true

  • MediaCentral Asset Management: depends on the option "Allow overlapping segments" for a stratum’s datamodel, it defaults to false

flags

A list of flags that define certain aspects of the layer. Currently, the following flags are supported:

  • readonly: the layer should be displayed in a read-only mode.

attributes

An array defining the attributes that are available for the layer. The definition of the attributes for the layer uses the same structure as for the attributes for the asset. See attributes for details.

Example for a layer of time-based annotation 
 
{
    "attributes":{
        …​
    },
    "time-based":[
        {
            "id":"EDITORIAL_CONTENT",
            "description":"Editorial content",
            "labels":{
                "en":"Editorial content",
                "de":"Inhalt"
            },
            "tooltips":{
                …​
            },
            "ranged":true,
            "gaps":true,
            "overlap":false,
            "flags":[
                "indexed",
                "readonly"
            ],
            "attributes":[
                {
                    "id":"comment",
                    "description":"Comment for the segment",
                    "labels":{
                        "en":"Comment"
                    },
                    "tooltips":{
                        …​
                    },
                    "type":{
                        "baseType":"string"
                    },
                    "flags":[
                        "readonly"
                    ]
                },
                {
                    "id":"reporter",
                    "labels":{
                        "en":"Reporter"
                    },
                    "type":{
                        "baseType":"string"
                    }
                }
            ]
        }
    ],
    "layout":{
        …​
    }
}

layout

The property layout contains a map of Meta data layouts. The key is the type of layout. The value depends on the layout type. Currently, the following layout types are defined:

  • attributeGroupLayout: a layout based on groups of attributes. See Attribute group layout for details.

  • simpleTimeBasedLayout: a simple layout for time-based annotation. See Simple time-based layout for details.

  • virtualLayersLayout: allow to express combinations of layers having specific semantics. See Virtual layers layout for details.

Attribute group layout

Properties

The attributeGroupLayout property defines a layout is based on groups of attributes. It consists of an array of groups.

For each group, you have the following properties:

Property

Description

id

The ID of the attribute group

labels

The localized labels for the attribute group. The structure is the same as for attributes.

tooltips

The localized tooltips for the attribute group.

items

An array of items to be shown in the attribute group. Each item is an attribute as defined in the attributes property.

An item has the following properties:

Property Description

id

The ID of the attribute

common

(optional) true if the attribute is a common attribute, false, null or missing if the attribute is a custom attribute.

flags

(optional) May contain a list of flags defining how to display the attribute. Currently, the following flags are supported:

  • multiline: Display the attribute as a multi-line input control, e.g. as a "textarea" HTML control.

  • readonly: The layout mandates readonly handling.

  • mandatory: The attribute is mandatory, meaning that is must have a non-empty value.

options

(optional) May contain a map of options defining how to display the attribute. Currently, the following options are supported:

  • defaultFrameRate: The default framerate for attributes of type timecode and duration. This is a floating point value. It should only used if the asset doesn’t have a defined frame rate.

  • defaultFrameRateDropFrame: The default value for the dropframe behavior. This is a boolean value.

  • defaultValue: (deprecated) Default value for the attribute. For AM, the value returns the raw value from the data model as a string.

  • legalListSortType: (deprecated, use sort instead) The legallist sort type, if the attribute is of type.baseType "list". Its value can be "INDEX", "SHORTCUT", "LABEL" or "CUSTOMINDEX".

  • legalListSortOrder: (deprecated, use sort instead) The sort order of legallists, if the attribute is of type.baseType "list". Its value can be either "ascending" or "descending".

  • readOnlyExpression: (optional) ID of an expression, which determines the readonly state of the layout element.

  • readOnlyExpressionRule: (optional) The expression, which determines the readonly state of the layout element. See expressions for details.

  • restrictions: (optional) Additional restrictions for the attribute. The option is currently only given for MC | AM multi-value attributes. See Restrictions below for a list of restrictions.

  • sort: (optional, only for taxonomy attributes) Recommended default sort order. The value is a string that can be used directly as query parameter sort when calling taxonomies:entries or taxonomies:search. The value is a comma-separated list of sort specs, each consisting of an optional prefix (+=ascending, -=descending), followed by an attribute ID. Example: "sort": "ATHLETE_SURNAME,ATHLETE_FIRSTNAME,-ATHLETE_BIRTHDAY" to sort primarily by surname in ascending order, then by first name in ascending order, then by birthday in descending order.

  • visibilityExpression: (optional) ID of an expression, which determines the visibility of the layout element.

  • visibilityExpressionRule: (optional) The expression, which determines the visibility of the layout element. See expressions for details.

subitems

(optional) Array of sub-items of the item, e.g. to represent the layout of MVC-attributes in MediaCentral Asset Management. The structure of subitems' elements is equivalent to those of items.

Restrictions

The option restrictions may contain additional restrictions that a UI should impose when displaying an attribute. Currently, the restrictions option is only used for multi-value attributes and only present if there are restrictions. The value is a JSON object that may contain the following properties:

Property

Description

noCreateRows

(optional, boolean) Only for MC | AM multi-value attributes: if present and value is true, the user shall not be able to create new rows.

noCreateRowsExpression

(optional) Only for MC | AM multi-value attributes: if present and not null, the value is an expression (see expressions for details). If the expression evaluates to true, the user shall not be able to create new rows. An expression is only given if noCreateRows is not given or false.

noDeleteRows

(optional, boolean) Only for MC | AM multi-value attributes: if present and value is true, the user shall not be able to delete rows.

noDeleteRowsExpression

(optional) Only for MC | AM multi-value attributes: if present and not null, the value is an expression (see expressions for details). If the expression evaluates to true, the user shall not be able to delete rows. An expression is only given if noDeleteRows is not given or false.

noMoveRows

(optional, boolean) Only for MC | AM multi-value attributes: if present and value is true, the user shall not be able to delete rows.

noMoveRowsExpression

(optional) Only for MC | AM multi-value attributes: if present and not null, the value is an expression (see expressions for details). If the expression evaluates to true, the user shall not be able to move rows. An expression is only given if noMoveRows is not given or false.

Example

Example for an attribute group layout "VIDEO" with two groups "Video" and "MPI", with two attributes each 
 
{
  "attributes": { …​ },
  "time-based": [ …​ ],
  "layout": {
    "attributeGroupLayout": [
      {
        "id": "VIDEO",
        "labels": {
          "en": "Video"
        },
        "items": [
          {
            "id": "name",
            "common": true
          },
          {
            "id": "ORIGINAL_FILENAME",
            "flags": [
              "multiline"
            ],
            "options": {
              "default": {
                "value": "-- unknown file name --"
              }
            }
          },
          {
            "id": "ORIGINAL_EXTENSION"
          }
        ]
      },
      {
        "id": "XTRA_15_MPI",
        "labels": {
          "en": "MPI"
        },
        "items": [
          {
            "id": "MPI_EXTERNAL_ID"
          },
          {
            "id": "PAM_MASTERCLIP_TAPE"
          }
        ]
      }
    ]
  }
}

Simple time-based layout

The simpleTimeBasedLayout property defines a simple layout that can be used to display and edit layers of time-based annotation.

The value of simpleTimeBasedLayout is an array, containing one object for each layer (in the example for the layer with ID EDITORIAL_CONTENT) in the sequence in which the layers should be displayed. For each layer the following properties are available:

Property

Description

id

The ID of the layer.

items

An array of items to be shown for this layer. Each item is an attribute as defined in the attributes property of this layer of time-based annotation.

Each item has the following properties:

Property

Description

id

The ID of the attribute.

flags

(optional) Flags may specify how to show the attribute. Currently the following flags are supported:

  • readonly: Display as read-only field.

  • multiline: Display the attribute as a multi-line input control, e.g. as a "textarea" HTML control.

options

(optional) May contain a map of options defining how to display the attribute. Currently, the following options are supported:

  • defaultFrameRate: The default framerate for attributes of type timecode and duration. This is a floating point value. It should only used if the asset doesn’t have a defined frame rate.

  • defaultFrameRateDropFrame: The default value for the dropframe behavior. This is a boolean value.

  • legalListSortType: (deprecated, use sort instead) The legallist sort type, if the attribute is of type.baseType "list". Its value can be "INDEX", "SHORTCUT", "LABEL" or "CUSTOMINDEX".

  • legalListSortOrder: (deprecated, use sort instead) The sort order of legallists, if the attribute is of type.baseType "list". Its value can be either "ascending" or "descending".

  • readOnlyExpressionRule: (optional) The expression, which determines the readonly state of the layout element. See expressions for details.

  • sort: (optional, only for taxonomy attributes) Recommended default sort order. The value is a string that can be used directly as query parameter sort when calling taxonomies:entries or taxonomies:search. The value is a comma-separated list of sort specs, each consisting of an optional prefix (+=ascending, -=descending), followed by an attribute ID. Example: "sort": "ATHLETE_SURNAME,ATHLETE_FIRSTNAME,-ATHLETE_BIRTHDAY" to sort primarily by surname in ascending order, then by first name in ascending order, then by birthday in descending order.

Example for an simple time-based layout for layer "EDITORIAL_CONTENT" with two attributes 
 
{
    "attributes":{
        …​
    },
    "time-based":[
        …​
    ],
    "layout":{
        "simpleTimeBasedLayout":[
            {
                "id":"EDITORIAL_CONTENT",
                "items":[
                    {
                        "id":"comment",
                        "flags":[
                            "multiline"
                        ]
                    },
                    {
                        "id":"reporter"
                    }
                ]
            }
        ]
    }
}

Virtual layers layout

The idea of the property virtualLayersLayout is to express combinations of layers having specific semantics.

The value of virtualLayersLayout is an array, containing one object for each virtual layer. For each virtual layer the following properties are available:

Property

Description

id

The ID of the virtual layer having specific semantics.

layerids

An array of other layer IDs (taken from those specified in the simpleTimeBasedLayout property), whose combination defines the virtual layer.

MediaCentral Production Management: Provides two virtual layers: "markers" and "restrictions".

Example for a virtual layer layout for MediaCentral Production Management 
 
{
  "attributes": { …​ },
  "time-based": [ …​ ],
  "layout": {
    "virtualLayersLayout": [
      {
        "id": "markers",
        "layerids": [
          "V1",
          "V2",
          "V3",
          "A1",
          "A2",
          "A3",
          "A4"
        ]
      },
      {
        "id": "restrictions",
        "layerids": [
          "restrictions"
        ]
      }
    ]
  }
}

Expressions

Expressions are used as values of the options readOnlyExpressionRule and visibilityExpressionRule. An expression is a recursive JSON structure. It consists of an arbitrary combination of AND and OR clauses, combined with attribute terms.

Example for a read-only expression 
 
{
    "or":[
        {
            "and":[
                {
                    "attribute":"ASPECT_RATIO",
                    "op":"isSet"
                },
                {
                    "attribute":"SHOW_TITLE",
                    "op":"equals",
                    "value":"heute journal"
                }
            ]
        },
        {
            "and":[
                {
                    "attribute":"ASPECT_RATIO",
                    "op":"isSet"
                },
                {
                    "attribute":"BROADCASTER",
                    "op":"equals",
                    "value":"ZDF"
                }
            ]
        }
    ]
}

The following expressions are supported:

Expression type

Description

AND clause

True, if all sub expressions evaluate to true:

{
  "and": [
    { ... }, // sub expression 1
    { ... }  // sub expression 2
  ]
}

OR clause

True, if at least one of the sub expressions evaluates to true:

{
  "or": [
    { ... }, // sub expression 1
    { ... }  // sub expression 2
  ]
}

Attribute term without arguments

Test the value of a given attribute. Valid ops:

  • isSet: True, if the attribute is set to a non-empty value.

  • isNotSet: True if the attribute is set to an empty string or to null.

{
  "attribute": "MAINTITLE",
  "op": "isSet"
}

Attribute term with one argument

Test the value of a given attribute against a given value. Valid ops:

  • equals: True if the attribute has exactly the value given in the property value, case-insensitive, without anything before or after it.

  • notEquals: True if the attribute does not have exactly the value given in the property value, case-insensitive.

  • contains: (Only for string attributes) True if the attribute contains the value given in the property value anywhere as a sub string, case-insensitive.

  • notContains: (Only for string attributes) True if the attribute doesn’t contain the value given in the property value anywhere as a sub string, case-insensitive.

{
  "attribute": "MAINTITLE",
  "op": "equals"
  "value": "Example"
}

The value property always contains a string. Example for an integer attribute:

{
  "attribute": "AN_INTEGER_ATTRIB",
  "op": "notEquals"
  "value": "42"
}

If an attribute has no value or if the value property of the expression is null, it must be treated like an empty string. Examples:

  • equals "": true if the attribute contains an empty string or has no value.

  • contains "": always true.

  • notEquals "abc": true if the attribute has no value or if the value is not "abc".

  • notEquals "": true if the attribute has a non-empty value.

MediaCentral | Asset Management:

  • The value is exactly the value in the configured data model, with two exceptions: for boolean attributes, the value "0" in the data model is returned here as "true", and the value "1" in the data model is returned here as "false". This ensures that the values correspond to the values returned when querying the aa:attributes resource for an asset.

  • Conditions for attributes of types date, time, datetime, timecode and duration might not work exactly as in classic MC | AM Desktop. If you have expressions using those types of attributes, you should verify if they still work as expected and adapt them to the CTMS format for the attribute type.

Attribute term with a list of arguments

Test the value of a given attribute against list of given values. Valid ops:

  • in: True if the attribute has exactly any of the values given in the property values, case-insensitive, without anything before or after it.

  • notIn: True if the attribute has none of the values given in the property values, case-insensitive, without anything before or after it.

{
  "attribute": "MAINTITLE",
  "op": "in"
  "values": [
    "Berlin",
    "Kaiserslautern",
    "New York"
  ]
}

Again, the values property always contains JSON strings. And if an attribute has no value or if the value property of the expression is null, it must be treated like an empty string.

For MediaCentral | Asset Management, the same rules for the values apply as for attribute terms with one argument (see above).

Complete Example

Example for an MC|AM asset 
 
{
  "_links": {
    "self": {
      "href": "https://host/…​"
    }
  },
  "attributes": {
    "common": [
      {
        "id": "name",
        "labels": {
          "en": "Main Title"
        },
        "type": {
          "baseType": "string",
          "maxLength": 256
        },
        "options": {
          "mandatory": true
        }
      },
      {
        "id": "modified",
        "labels": {
          "en": "Modified"
        },
        "type": {
          "baseType": "datetime"
        }
      }
    ],
    "custom": [
      {
        "id": "ORIGINAL_FILENAME",
        "labels": {
          "en": "Original Filename (changed)"
        },
        "type": {
          "baseType": "string",
          "maxLength": 256
        }
      },
      {
        "id": "ORIGINAL_EXTENSION",
        "labels": {
          "en": "Original Extension"
        },
        "type": {
          "baseType": "string",
          "maxLength": 256
        },
        "options": {
          "readonly": true
        }
      }
    ]
  },
  "time-based": [
    {
      "id": "EDITORIAL_CONTENT",
      "description": "Editorial content",
      "labels": {
        "en": "Editorial content",
        "de": "Inhalt"
      },
      "tooltips": { …​ },
      "ranged": true,
      "gaps": true,
      "overlap": false,
      "flags": [
        "indexed",
        "readonly"
      ],
      "attributes": [
        {
          "id": "comment",
          "description": "Comment for the segment",
          "labels": {
            "en": "Comment"
          },
          "tooltips": { …​ },
          "type": {
            "baseType": "string"
          },
          "flags": [
            "readonly"
          ]
        },
        {
          "id": "reporter",
          "labels": {
            "en": "Reporter"
          },
          "type": {
            "baseType": "string"
          }
        }
      ]
    }
  ],
  "layout": {
    "attributeGroupLayout": [
      {
        "id": "VIDEO",
        "labels": {
          "en": "Video"
        },
        "items": [
          {
            "id": "name",
            "common": true
          },
          {
            "id": "ORIGINAL_FILENAME",
            "flags": [
              "multiline"
            ],
            "options": {
              "defaultValue": "-- unknown file name --"
            }
          },
          {
            "id": "ORIGINAL_EXTENSION"
          }
        ]
      },
      {
        "id": "XTRA_15_MPI",
        "labels": {
          "en": "MPI"
        },
        "items": [
          {
            "id": "MPI_EXTERNAL_ID"
          },
          {
            "id": "PAM_MASTERCLIP_TAPE"
          }
        ]
      }
    ],
    "simpleTimeBasedLayout": [
      {
        "id": "EDITORIAL_CONTENT",
        "items": [
          {
            "id": "comment",
            "flags": [
              "multiline"
            ]
          },
          {
            "id": "reporter"
          }
        ]
      }
    ],
    "virtualLayersLayout": [
      {
        "id": "markers",
        "layerids": [
          "V1",
          "V2"
        ]
      },
      {
        "id": "blubb",
        "layerids": [
          "x",
          "y",
          "z"
        ]
      }
    ]
  }
}