Metadata Model [ENT 21.1 ARC]
All Vidispine Enterprise MAM products build on the metadata model defined and implemented by VidiCore. All possibilities and the technical details around it are documented in VidiCore’s APIdoc. This page focuses on the metadata model as used in the Enterprise MAM products VidiFlow, VidiEditor, MediaEditor, and EditMate.
Fields
Metadata are stored in fields. Fields are typed and can have one of the data types listed in APIdoc. Depending on the data type the field values can be restricted in a certain way. By default, fields are searchable which means that their values are replicated to the VidiCore search index on Elasticsearch. Marking fields as not searchable where applicable helps reducing the size of the VidiCore search index.
VidiCore distinguishes between three different types of metadata fields: user-defined metadata, system-defined metadata, and transient metadata.
User-Defined Metadata
User-defined metadata can be configured depending on the concrete needs of the system to build. They are stored in the VidiCore database as entities of their own and can be attached to items, collections, and further top-level entities of VidiCore.
VidiCore imposes certain rules on the field names which are respected by the Enterprise MAM Solution. By convention, all user-defined metadata fields in Enterprise MAM start the the prefix V3_.
In Enterprise MAM all fields and their properties can be configured in ConfigPortal:
Different Enterprise MAM products come with pre-defined product-specific metadata. From VidiCore’s perspective these are user-defined, too. By convention, these fields start with a two-character prefix denoting the product:
Product | Historical Product Name | Prefix |
|---|---|---|
VidiFlow | Platform |
|
VidiEditor | MediaEditor |
|
MediaPortal | n/a |
|
EditMate | n/a |
|
MediaIngest | Origin |
|
These fields cannot be changed in ConfigPortal but are listed as read-only and can be used for further configuration aspects (e.g. metadata masks for front-end applications).
Example showing the Enterprise MAM standard metadata field V3_Hidden:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ItemDocument id="ITEM-VX-5336" xmlns="http://xml.vidispine.com/schema/vidispine">
<metadata>
<revision>VX-148354,VX-148352,VX-148351,VX-148346,VX-148345,VX-148344,VX-148343</revision>
<timespan start="-INF" end="+INF">
[...]
<field uuid="046f29a8-8ff4-48bd-8e29-c73d0436b13f" user="dave.default" timestamp="2021-02-02T15:43:07.511Z" change="VX-148343">
<name>V3_Hidden</name>
<value uuid="4ced6b57-94e7-4a17-a5bb-040265d081a7" user="dave.default" timestamp="2021-02-02T15:43:07.511Z" change="VX-148343">true</value>
</field>System-Defined Metadata
System-defined metadata are pre-defined by VidiCore. Their definitions cannot be changed. With the single exception of the title field also their values cannot be changed. Only VidiCore itself can set the values.
System-defined metadata are also stored in the VidiCore database as entities of their own. They cannot be changed in ConfigPortal but are listed as read-only and can be used for further configuration aspects (e.g. metadata masks for front-end applications).
A complete list of system-defined metadata is available in VidiCore APIdoc.
Example showing the system-defined metadata title and shapeTag:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ItemDocument id="ITEM-VX-5348" xmlns="http://xml.vidispine.com/schema/vidispine">
<metadata>
<revision>VX-148715,VX-148710,VX-148709,VX-148714,VX-148713,VX-148712</revision>
<timespan start="-INF" end="+INF">
<field uuid="639bca2f-9c2f-4400-9907-70499fefae45" user="system" timestamp="2021-02-03T09:58:15.305Z" change="VX-148715">
<name>shapeTag</name>
<value uuid="698ee5bf-e9ec-4730-83b0-381a1b6aedf2" user="system" timestamp="2021-02-03T09:58:15.305Z" change="VX-148715">original</value>
</field>
<field uuid="dcead969-bb9b-4813-86dd-05be6645c78a" user="admin" timestamp="2021-02-03T09:58:01.650Z" change="VX-148709">
<name>title</name>
<value uuid="97113c67-03e3-4db8-9ce4-6b44b4ea8ca4" user="admin" timestamp="2021-02-03T09:58:01.650Z" change="VX-148709">Nasa Football 2</value>
</field>
[...]Transient Metadata
Transient metadata are not stored in the VidiCore database as separate entities. Instead, they are derived from other information in the database and only returned in the structure of metadata fields whenever metadata for an item or collection are fetched via the API. They cannot be changed in ConfigPortal but are listed as read-only and can be used for further configuration aspects (e.g. metadata masks for front-end applications).
Transient metadata always are searchable.
A complete list of transient metadata is available in VidiCore APIdoc.
Example showing several transient metadata:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ItemDocument id="ITEM-VX-5348" xmlns="http://xml.vidispine.com/schema/vidispine">
<metadata>
<revision>VX-148715,VX-148710,VX-148709,VX-148714,VX-148713,VX-148712</revision>
<timespan start="-INF" end="+INF">
[...]
<field>
<name>__user</name>
<value>admin</value>
</field>
<field>
<name>__metadata_last_modified</name>
<value>2021-02-03T09:58:15.305Z</value>
</field>
<field>
<name>__placeholder_shape_size</name>
<value>0</value>
</field>
<field>
<name>__shape_size</name>
<value>2</value>
</field>
<field>
<name>__shape</name>
<value>SHAPE-VX-7581</value>
</field>
<field>
<name>__shape</name>
<value>SHAPE-VX-7582</value>
</field>
[...]Fields With Multiple Values
Fields can have multiple values, too. This makes sense for certain system-defined fields like shapeTagwhich may have multiple values if the item contains multiple shapes. It may also be used for modelling tags.
Example showing a field with multiple values:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ItemDocument id="ITEM-VX-5218" xmlns="http://xml.vidispine.com/schema/vidispine">
<metadata>
<revision>VX-145614,VX-145613,VX-145618,VX-145616,VX-145619,VX-145610,VX-145609</revision>
<timespan start="-INF" end="+INF">
<field uuid="722bc0f3-d266-4f70-be05-06ea259517f5" user="system" timestamp="2021-01-14T19:26:45.544Z" change="VX-145618">
<name>shapeTag</name>
<value uuid="57f130ee-d53d-408c-8901-9f7b35eff8bd" user="system" timestamp="2021-01-14T19:26:45.544Z" change="VX-145618">original</value>
<value uuid="993c5cb8-7b8c-48fd-a6db-737b8500db3a" user="system" timestamp="2021-01-14T19:26:45.544Z" change="VX-145618">__mp4</value>
</field>
[...]Groups
Groups allow structuring metadata. Groups may contain one or more fields. Groups can also contain other groups as subgroups to build a hierarchical structure.
Example:
<ItemDocument id="ITEM-VX-4814" xmlns="http://xml.vidispine.com/schema/vidispine">
<metadata>
<revision>VX-134684,VX-135083,VX-134683,VX-134674,VX-134678,VX-134675,VX-145273,VX-145272,VX-134680,VX-134679</revision>
[...]
<timespan start="28@PAL" end="56@PAL">
<group uuid="a0828c45-5b7d-48bb-ae9a-499e1c51c855" user="dave.admin" timestamp="2021-01-12T12:54:07.211Z" change="VX-145273">
<name>V3_Company</name>
<field uuid="6ac1c357-0202-43cf-aade-8263a1487cb9" user="dave.admin" timestamp="2021-01-12T12:54:07.211Z" change="VX-145273">
<name>V3_Name</name>
<value uuid="b5abe68b-f7bc-4581-9707-fb7cb08d8896" user="dave.admin" timestamp="2021-01-12T12:54:07.211Z" change="VX-145273">The Builders</value>
</field>
<field uuid="522c3afd-88d6-452c-beeb-849b21781fb1" user="dave.admin" timestamp="2021-01-12T12:54:07.211Z" change="VX-145273">
<name>V3_Location</name>
<value uuid="9be1f847-2c59-4457-ad8c-1594aa390128" user="dave.admin" timestamp="2021-01-12T12:54:07.211Z" change="VX-145273">Far Out</value>
</field>
<group uuid="6ef4a15f-ddcf-40cd-b191-816c55252b58" user="dave.admin" timestamp="2021-01-12T12:53:52.136Z" change="VX-145272">
<name>V3_Employee</name>
<field uuid="91e1c856-d8e4-440c-a5c5-c59c839a4639" user="dave.admin" timestamp="2021-01-12T12:53:52.136Z" change="VX-145272">
<name>V3_Name</name>
<value uuid="a9e11291-cb83-4ab9-a9c0-a70edc938c15" user="dave.admin" timestamp="2021-01-12T12:53:52.136Z" change="VX-145272">Alice</value>
</field>
<field uuid="448c04c0-d97e-4c8a-8a73-ac468dbed03b" user="dave.admin" timestamp="2021-01-12T12:53:52.136Z" change="VX-145272">
<name>V3_Title</name>
<value uuid="3c8ce3bd-b2ad-47ae-9799-9a52e70615e6" user="dave.admin" timestamp="2021-01-12T12:53:52.136Z" change="VX-145272">CEO</value>
</field>
</group>
</group>
</timespan>
[...]Timespans
When attaching metadata fields or groups to an item or a collection, there’s always a timespan in between. The timespan describes which part of the items or collections timeline the metadata refer to.
A timespan consists of a start time code and and end time code in the standard VidiCore notation. Both time codes are relative to the start of the visible portion of the asset. The start time code is inclusive whereas the end time code is exclusive so that start and end time code denote a half-open interval [start,end).
The generic timespan [-INF,+INF) denotes the complete item or collection.
Items And Collections
Metadata fields and groups can be attached to VidiCore items and VidiCore collections in the same way.
Metadata Inheritance
Metadata fields and groups can be marked as inheritable. When such fields and groups are attached to a collection, VidiCore will automatically inherit them to all items in this collection. If a child collection is placed into a parent collection, all inheritable metadata from the parent collection will be inherited to the child collection(s) recursively to all child-collections and the items in them.
Inheritance can be broken by setting a field value directly on an item or a sub-collection. If you set the the V3_Programme field on ITEM-VX-42 to Another Universe explicitly the value Our Universe originally inherited from COLLECTION-VX-17 will not be available on ITEM-VX-42 any more:
Metadata References
Instead of directly settings the values of a metadata field or group you can also refer to a field or group value on an existing item, collection, or document by using weak references.
These weak references have the effect that metadata changes on the source field/group are automatically reflected to the destination field/group.
When retrieving metadata for items or collections the values coming to that item/collection via weak references look exactly the same if they were set directly on the item. Only the additional element <referenced> on the field or group value tells you that this is a weak reference:
<field uuid="1cce8c81-c3d5-4113-9004-54b6b9161318" user="admin" timestamp="2021-02-02T10:49:20.681Z" change="VX-147833">
<name>V3_CompanyName</name>
<referenced id="ITEM-VX-2" uuid="1344f9a2-6a0a-4c29-82e7-76fef176ec7a" type="item"/>
<value uuid="02664b6b-0d5f-4b39-b3ee-9f66a455f769" user="dave.admin" timestamp="2021-01-06T13:01:59.736Z" change="VX-144022">Arvato Systems S4M GmbH</value>
</field>Searching for these metadata works exactly the same way as if the values were set directly on the item/collection.
Further details can be found in VidiCore APIdoc.
Document Metadata
VidiCore metadata is most cases are attached to items and collections as described above. For some scenarios it may be useful, however, to store metadata documents outside of items or collections in a more global manner.
For this purpose VidiCore offers document metadata. Document metadata are a key-value storage where the key is an arbitrary string and the value is a VidiCore MetadataDocument. These documents can server as storage for system-wide information. You can refer to metadata stored in documents via weak references as described in the previous section.
A small caveat with document metadata is that the keys are not generated automatically (as with item or collections ids), so you need to define your own naming scheme to avoid conflicts with all applications connecting to the same VidiCore.
Enums
Enums are defined as fields where the user can only select from a pre-defined set of values. Multiple enums can depend on each other: the value selected in one enum may restrict the possible values in another enum.
Let’s assume our system has configured the enums V3_Country and V3_City. Both have their possible set of values:
When Germany is set on V3_Country the possible values for V3_City are restricted to Cologne and Gütersloh:
When selecting Malaysia as country the allow values for V3_City changes:
Enums are modelled as metadata data sets in VidiCore. The VidiCore API ensures that the restrictions of the data sets are met for every change on such fields.
Extending Enums With Additional Data
In some scenarios you need additional data on each value of an enum field. An example is a list of sports teams where the user can select a specific team from a list of teams. The team selection would be via a regular enum metadata field. The enum key would be a (technical) team id (e.g. basketball-tor for the Toronto Raptors basketball team), the enum value would be a display string for this team (e.g. “Toronto Raptors (TOR)”).
All additional information on the team (e.g. home stadium, sponsor names, etc.) can be stored in VidiCore document metadata. The enum key is used as the name of the document. All further information is stored as regular VidiCore metadata on this document.
When the user selects “Toronto Raptors (TOR)”) from the enum, the enum key would be basketball-tor. This key can be used to directly look up the corresponding document via
GET /API/document/basketball-torto retrieve the whole metadata document associated with this team.
The metadata groups or fields in this document can either be copied to an item or a collection – or a metadata reference can be used to link the document to an item or collection.