Metadata inheritance

Inheritance

Metadata fields and groups can be marked as inheritable. Inheritable metadata set on a collection will be inherited to all items in the collection. If an inheritable field is set on the collection and the item, the value on the item takes precedence.

To enable metadata inheritance add the attribute inheritance="true" to the root element of the MetadataFieldDocument:

PUT /metadata-field/event_rating HTTP/1.1
Content-Type: application/xml

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine" inheritance="true">
  <type>integer</type>
  <integerRestriction>
    <minInclusive>1</minInclusive>
    <maxInclusive>5</maxInclusive>
  </integerRestriction>
</MetadataFieldDocument>

When retrieving an item with inherited metadata the attribute inheritance on the field element will contain the ID of the collection from which the field was inherited:

GET /item/VX-51/metadata HTTP/1.1
Accept: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item id="VX-51">
        <metadata>
            <revision>VX-206,VX-146,VX-145,VX-154</revision>
            <timespan start="-INF" end="+INF">
                ...
                <field inheritance="Collection/VX-6" uuid="9beea1d8-0560-40c2-bfaf-03ff2dd5f02e" user="admin" timestamp="2018-03-14T13:23:14.238+01:00" change="VX-148">
                    <name>event_rating</name>
                    <value uuid="593e6678-1ace-4d69-9362-1add839024bf" user="admin" timestamp="2018-03-14T13:23:14.238+01:00" change="VX-148">3</value>
                </field>
                ...
            </timespan>
        </metadata>
    </item>
</MetadataListDocument>

Relative timespan inheritance

New in version 5.0.

By setting the absoluteTime attribute in the CollectionDocument, timespans inherited from a collection are individually offset by the startTimeCode value of child items. In other words, timespans set on the collection are interpreted as absolute, and converted to the usual relative (zero-based) timecodes for each item.

Example

To create a collection using this feature:

POST /collection?name=Sports-Game
Accept: application/xml

<CollectionDocument absoluteTime="true" xmlns="http://xml.vidispine.com/schema/vidispine">
</CollectionDocument>

If this collection contains an item with metadata field startTimeCode with value 100@PAL:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
        <timespan start="-INF" end="+INF">
            <field>
                <name>startTimeCode</name>
                <value>100@PAL</value>
            </field>
        </timespan>
</MetadataDocument>

and the collection metadata contains an inheritable field, in this case a custom field called goal:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
        <timespan start="500@PAL" end="1000@PAL">
            <field>
                <name>goal</name>
                <value>by John Smith</value>
            </field>
        </timespan>
</MetadataDocument>

The metadata on the item then shows the time of the inherited field relative to its startTimeCode value:

GET /item/VX-1/metadata

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    ...
    <timespan end="400@PAL" start="900@PAL">
        <field>
            <name>goal</name>
            <value>by John Smith</value>
        </field>
    </timespan>
    ...
</MetadataDocument>

The default behaviour when absoluteTime is false or not set, or no startTimeCode is set on the item, is that that timespans are inherited unchanged from the collection.

See also filterInheritedTimespans.

Inheritance Rules

Inheritance rules can be used to set one or more rules when a field should be inherited. It is also possible to, per rule, configure the field to be inherited with another name.

Example

Let’s say that we have an hierarchy of collections that represents TV shows, seasons and episodes, and that we want to have a title set on each collection. We also want to use inheritance, so that the season collection has the show title and the episode collection has both the show title and the season title in its metadata.

We can implement this using inheritance rules. This example will use two metadata-fields that will be set on all entities: asset_type and asset_title, as well as the metadata-fields that will be used by the inheritance rules.

PUT /metadata-field/asset_type
    /metadata-field/asset_title_Show
    /metadata-field/asset_title_Season
    /metadata-field/asset_title_Episode

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <type>string</type>
</MetadataFieldDocument>

When the metadata fields above has been created, we can create the asset_title field, which will have the inheritance rules:

PUT /metadata-field/asset_title

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine" inheritance="true">
    <type>string</type>
    <inheritanceRule>
        <condition>
            <field>
                <name>asset_type</name>
                <value>Show</value>
            </field>
        </condition>
        <inheritedName>asset_title_Show</inheritedName>
    </inheritanceRule>
    <inheritanceRule>
        <condition>
            <field>
                <name>asset_type</name>
                <value>Season</value>
            </field>
        </condition>
        <inheritedName>asset_title_Season</inheritedName>
    </inheritanceRule>
    <inheritanceRule>
        <condition>
            <field>
                <name>asset_type</name>
                <value>Episode</value>
            </field>
        </condition>
        <inheritedName>asset_title_Episode</inheritedName>
    </inheritanceRule>
</MetadataFieldDocument>

Now we can set asset_type and asset_title on the collections. The asset_title field will be inherited and renamed based on the rules above.

../../_images/inheritancerule.png

Additional notes

For a condition to match, the field must exist in the same timespan as the field that is inherited. The field must also only have one value set. In the example above, both asset_type and asset_title must be in the same timespan.

If no condition is met, the field is not inherited at all. In the example above, if an entity has asset_type set to e.g. “Extra” then asset_title will not be inherited from it.