The metadata of an item consists of fields, groups and values that belong to a specific interval or timespan. Metadata that does not apply to a specific interval, that is, it is non-timed, belong to the timespan with a start and end of -INF and +INF, respectively.

  • A timespan describes an interval within the item, denoted by two time codes (a start value and an end value).

  • A timespan contains sets of fields and groups.

  • Groups are named sets of fields and groups.

  • Fields have a name and a set of values of a specific type.

In addition, metadata can apply to a specific component track, identified by a track name, for example, A1 or V1 (a name on the regular expression form [A-Za-z]+[1-9][0-9]*), and a specific language, typically a ISO 639 language code.

Examples of usage can be found at Creating fields/groups, modifying and moving metadata.

Fields

Before you can use fields and groups in the metadata of an item you need to define them. When defining a field you must select its data type, that is, the type of values that will be accepted for the field. You can also restrict values further by adding additional restrictions to the field.

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

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <type>string-exact</type>
    <stringRestriction>
      <pattern>[a-z]+</pattern>
    </stringRestriction>
</MetadataFieldDocument>
NONE
HTTP/1.1 200 OK
NONE

Field identifiers

Metadata field ids are case sensitive and must have a certain format to avoid conflicts with existing and possible future fields used by Vidispine or other partners.

A metadata field id (name) is one of:

  • Core set, the standard metadata set. Metadata field ids are assigned by Vidispine, and are of the regular expression form: [A-Za-z][A-Za-z0-9]*. maximum 32 characters.

  • Common set. Metadata field ids have the form { category } _ { field-name }. The category is of the regular expression form: [A-Za-z][A-Za-z0-9]*, maximum 4 characters, and assigned by Vidispine to be used by industry partners. field-name is the regular expression form: [A-Za-z][A-Za-z0-9]*. Total length of id is maximum 32 characters, including the underscore ( _ ) character.

  • Custom set. Metadata field ids have the form { custom-name } _ { field-name }. The custom-name is of the regular expression form: [A-Za-z][A-Za-z0-9]*, minimum 5 characters, and assigned by Vidispine. field-name is the regular expression form: [A-Za-z][A-Za-z0-9]*. Total length of id is maximum 32 characters, including the underscore ( _ ) character.

Data types

The data types at your disposal are:

Data type

Description

date

An ISO-8601 compatible timestamp.

float

A floating point value.

integer

A 32-bit signed integer value.

long

A 64-bit signed integer value.

string

A string.

string-exact

A string that uses exact matching.

boolean

A boolean value.

timeCode

A time code value.

string vs string-exact

During index time, the value of a string field is broken into small tokens, and then processed by various filters before been indexed. By doing so, users would get nice phrase search results, but loose the ability of “exact match”.

The value of a string-exact field, on the other hand, is indexed directly as a single token. This makes a “exact match” possible, and leads to smaller index size.

Note: In order to make search working properly, a re-index is required if the filed type is changed.

Noindex-types

Deprecated since version 4.1: The index element on the metadata field should be used instead to control if a field should be indexed.

Use the noindex types for fields that will contain data that should not be indexed, for example if it will never be searched for or if it contains data in some format, for example JSON or Base64-encoded binary data.

Data type

Description

date-noindex

An ISO-8601 compatible timestamp. No indexing will take place.

float-noindex

A floating point value. No indexing will take place.

integer-noindex

A 32-bit signed integer value. No indexing will take place.

long-noindex

A 64-bit signed integer value. No indexing will take place.

string-noindex

A string. No indexing will take place.

boolean-noindex

A boolean value. No indexing will take place.

timeCode-noindex

A time code value. No indexing will take place.

Sortable types

Deprecated since version 3.2: Sortable types are deprecated. This is since any field type can be used for sorting as long as it is indexed.

Sortable types can be used when searching to sort search results. A sortable field is one that uses a sortable types. Fields that are sortable have two limitations:

  1. They can only exist within non-timed metadata.

  2. They cannot contain lists of values.

Data type

Description

date-sortable

An ISO-8601 compatible timestamp. Can be used for sorting.

float-sortable

A floating point value. Can be used for sorting.

integer-sortable

An integer value. Can be used for sorting.

string-sortable

A string. Can be used for sorting.

string-exact-sortable

A string that uses exact matching. Can be used for sorting.

Restrictions

Add restrictions to metadata fields for further restrict the values that are to be allowed for a field. The table below shows the different types of restrictions that exist.

Data type

Parameter

Restriction

string

pattern

A Java compatible regular expression

minLength

A minimum allowed length of the string.

maxLength

A maximum allowed length of the string.

float

minInclusive

A minimum allowed value (inclusive).

maxInclusive

A maximum allowed value (inclusive).

integer

minInclusive

A minimum allowed value (inclusive).

maxInclusive

A maximum allowed value (inclusive).

long

minInclusive

A minimum allowed value (inclusive).

maxInclusive

A maximum allowed value (inclusive).

For example, adding a field that only accept integer values in the interval [1, 5].

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

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

The naming of your field must follow certain rules, see Field identifiers.

Default values

You can assign a default value to a field if you want a field to be included when retrieving the metadata of an item even if it has not been set.

Default values are added to the search index, meaning that searching for fields by the default value is possible.

If the default value is changed then the search index should be rebuilt using :http:put::/reindex/(index), or, the relevant items manually re-indexed using :http:put::/item/(item-id)/re-index.

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

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <type>integer</type>
  <defaultValue>0</defaultValue>
</MetadataFieldDocument>
NONE
HTTP/1.1 200 OK
NONE

Use the defaultValue parameter to control if the field should be included with the default value. Here item VX-12 does not have the field set:

GET /item/VX-12/metadata?field=testing_default&defaultValue=false HTTP/1.1
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-12">
    <metadata>
      <revision>VX-59,VX-60,VX-57</revision>
    </metadata>
  </item>
</MetadataListDocument>
HTML/XML
GET /item/VX-12/metadata?field=testing_default&defaultValue=true HTTP/1.1
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-12">
    <metadata>
      <revision>VX-59,VX-60,VX-57</revision>
      <timespan end="+INF" start="-INF">
        <field>
          <name>testing_default</name>
          <value>0</value>
        </field>
      </timespan>
    </metadata>
  </item>
</MetadataListDocument>
HTML/XML

Field groups

Metadata fields can be organized in zero or more field groups. Use groups to represents events or other types of objects in the metadata.

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

<MetadataFieldGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <data>
    <key>description</key>
    <value>An event in a clip</value>
  </data>
  <field>
    <name>event_type</name>
    <data>
      <key>text</key>
      <value>Here is some text.</value>
    </data>
  </field>
  <field>
    <name>event_rating</name>
  </field>
  <field>
    <name>event_text</name>
    <type>string</type>
    <data>
      <key>someextradata</key>
      <value>Some additional data</value>
    </data>
  </field>
  <access>
    <user>admin</user>
    <permission>DELETE</permission>
  </access>
</MetadataFieldGroupDocument>
NONE

Fields in a group that have not yet been created will be created for you. The example above also shows how additional metadata can be added to fields and groups.

Metadata schema

Finally, you can define a metadata schema to make sure that the metadata conforms to a specific data model.

For an example of how to define a metadata schema, see Defining a metadata schema. You can also define the schema when creating field groups, as shown in Alternate way of creating a schema.

There are three different types of elements in the schema: groups, fields and nested groups. They all have in common three attributes, name, min and max, and the two latter elements also have the attribute reference.

  • Name is the name of the field or group that the element refers to. The table below shows the semantics of a property for the different elements.

  • Min specifies the minimum of times that the element can occur in that context and is a non-negative integer.

  • Max specifies the maximum of times that the element can occur in that context and if set to a negative value it will be interpreted as an infinite number of times.

Group

Nested groups

Field

min

The minimum number of times that the group can occur at top-level.

The minimum number of times that the group can occur inside the given group

The minimum number of times the field can occur inside the given group

max

The maximum number of times that the group can occur at top-level.

The maximum number of times that the group can occur inside the given group

The maximum number of times the field can occur inside the given group

name

The name of the group.

The name of the group.

The name of the field.

reference

-

If set, controls whether the group must be a reference or not.

If set, controls whether the group must be a reference or not.

Top-level groups are used to specify what a fields and groups that they are allowed to contain. Furthermore they specify whether or not that group can exist outside of other groups. Nested groups and fields are used to specify the content of a top-level group.

Hierarchical metadata

Complex data relations can be represented with hierarchical metadata. Let’s say we have three classes in our data model, Organization, Employee and Project. An organization has a name, one or more employees and one or more projects. An employee has a name and a title. A project has a name and one or more employees assigned to it. This data model can be represented by using field groups to represent the classes and fields to represent the attributes.

Below an example of this data model is given:

As can be seen in the diagram, weak references are used in the project to point to the employees in the organization to avoid data duplication. An equivalent XML of the above diagram:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <group>
      <name>organization</name>
      <field>
        <name>name</name>
        <value>My organization</value>
      </field>
      <group uuid="c9be268e-03f4-4378-8061-e1c8b8f6b45c">
        <name>employee</name>
        <field>
          <name>name</name>
          <value>Bob</value>
        </field>
        <field>
          <name>title</name>
          <value>CEO</value>
        </field>
      </group>
      <group uuid="96a333b1-06f0-4975-adee-78b93c2a7614">
        <name>employee</name>
        <field>
          <name>name</name>
          <value>Pete</value>
        </field>
        <field>
          <name>title</name>
          <value>Director</value>
        </field>
      </group>
      <group uuid="82f92192-d2ef-422a-984a-b03cb0476a8a">
        <name>employee</name>
        <field>
          <name>name</name>
          <value>Andrew</value>
        </field>
        <field>
          <name>title</name>
          <value>Editor</value>
        </field>
      </group>
      <group>
        <name>project</name>
        <field>
          <name>name</name>
          <value>Movie project</value>
        </field>
        <field>
          <name>location</name>
          <value>London</value>
          <value>Berlin</value>
        </field>
        <group>
          <name>employee</name>
          <reference>96a333b1-06f0-4975-adee-78b93c2a7614</reference>
        </group>
        <group>
          <name>employee</name>
          <reference>82f92192-d2ef-422a-984a-b03cb0476a8a</reference>
        </group>
      </group>
    </group>
  </timespan>
</MetadataDocument>
HTML/XML

Metadata 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>
NONE

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>
NONE

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>
NONE

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>
HTML/XML

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>
HTML/XML

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

GET /item/VX-1/metadata
NONE
<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>
HTML/XML

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.

Versioning

Metadata essentially consists of key-value pairs. The key of a value is its UUID, but can also often be described by the quintuple (timespan, group, field name, track, language). However the latter does not guarantee unambiguity. If at any point a key corresponds to more than one value, then a conflict exists.

Change sets

A change set is a set of changes to the metadata. The change set has a unique id and can be related to other change sets. The current revision of the metadata is essentially the superset of all change sets.

Example

If we start with a newly imported item, its metadata might look like this:

GET item/VX-250/metadata
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-250">
    <metadata>
      <revision>VX-30</revision>
      <timespan end="+INF" start="-INF">
        <field>
          <name>durationSeconds</name>
          <value change="VX-30" timestamp="2010-03-19T09:08:09.563+01:00" user="system">232.32</value>
        </field>
        <field>
          <name>durationTimeCode</name>
          <value change="VX-30" timestamp="2010-03-19T09:08:09.576+01:00" user="system">232320000@1000000</value>
        </field>
      </timespan>
    </metadata>
  </item>
</MetadataListDocument>
HTML/XML

Assume two users, u1 and u2, both wants to add a title, not knowing of each others changes.

PUT item/VX-250/metadata?revision=VX-30
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan end="+INF" start="-INF">
    <field>
      <name>title</name>
      <value>u1's title</value>
    </field>
  </timespan>
</MetadataDocument>
NONE
PUT item/VX-250/metadata?revision=VX-30
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan end="+INF" start="-INF">
    <field>
      <name>title</name>
      <value>u2's title</value>
    </field>
  </timespan>
</MetadataDocument>
NONE

The result of the two operations will result in a conflict, because u2 did not know of the change made by u1.

GET item/VX-250/metadata
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item>
      <metadata>
         <revision>VX-30,VX-32,VX-31</revision>
         <timespan end="+INF" start="-INF">
            <field conflict="true">
               <name>title</name>
               <value change="VX-32" timestamp="2010-03-19T09:16:56.419+01:00" user="u2">u2's title</value>
               <value change="VX-31" timestamp="2010-03-19T09:16:25.454+01:00" user="u1">u1's title</value>
            </field>
            <field>
               <name>durationSeconds</name>
               <value change="VX-30" timestamp="2010-03-19T09:08:09.563+01:00" user="system">232.32</value>
            </field>
            <field>
               <name>durationTimeCode</name>
               <value change="VX-30" timestamp="2010-03-19T09:08:09.576+01:00" user="system">232320000@1000000</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>
HTML/XML

In order to resolve the conflict u1 inserts another change set:

PUT item/VX-250/metadata?revision=VX-30,VX-32,VX-31
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan end="+INF" start="-INF">
      <field>
         <name>title</name>
         <value>u1's and u2's title</value>
      </field>
   </timespan>
</MetadataDocument>
NONE

Which results in:

GET item/VX-250/metadata
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item>
      <metadata>
         <revision>VX-30,VX-33</revision>
         <timespan end="+INF" start="-INF">
            <field>
               <name>title</name>
               <value change="VX-33" timestamp="2010-03-19T09:21:28.692+01:00" user="u1">u1's and u2's title</value>
            </field>
            <field>
               <name>durationSeconds</name>
               <value change="VX-30" timestamp="2010-03-19T09:08:09.563+01:00" user="system">232.32</value>
            </field>
            <field>
               <name>durationTimeCode</name>
               <value change="VX-30" timestamp="2010-03-19T09:08:09.576+01:00" user="system">232320000@1000000</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>
HTML/XML

A graph of this can be seen below. Worth noting is that it is the leaves of the graph that represent the current revision.

Structure of metadata

Lists of values

A field can contain multiple values.

Example

Retrieving the current metadata:

GET /item/VX-250/metadata
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-7612">
      <metadata>
         <revision>VX-16113,VX-16114</revision>
         <timespan end="+INF" start="-INF">
            <field change="VX-16114" timestamp="2010-08-16T08:28:18.592+02:00" user="system" uuid="4cc88be0-4fc3-4243-a6e0-b1a151e6cde0">
               <name>shapeTag</name>
               <value change="VX-16114" timestamp="2010-08-16T08:28:18.592+02:00" user="system" uuid="b98a5553-a6ca-4235-bb14-fc17fdf7eda3">original</value>
            </field>
            <field change="VX-16113" timestamp="2010-08-16T08:28:18.366+02:00" user="admin" uuid="d35fb0ea-cd05-4429-a707-b248420b3fe7">
               <name>field_a</name>
               <value change="VX-16113" timestamp="2010-08-16T08:28:18.366+02:00" user="admin" uuid="31602cd8-4cfa-4912-a6fb-d731841f880c">my value</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>
HTML/XML

Adding a new value to field_a, if the mode attribute is left out the existing value will be modified instead of adding it as a new value.

PUT /item/VX-250/metadata
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="-INF" end="+INF">
      <field>
         <name>field_a</name>
         <value mode="add">my other value</value>
      </field>
   </timespan>
</MetadataDocument>
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item>
      <metadata>
         <revision>VX-16113,VX-16114,VX-16115</revision>
         <timespan end="+INF" start="-INF">
            <field change="VX-16115" timestamp="2010-08-16T08:35:18.550+02:00" user="admin" uuid="d35fb0ea-cd05-4429-a707-b248420b3fe7">
               <name>field_a</name>
               <value change="VX-16113" timestamp="2010-08-16T08:28:18.366+02:00" user="admin" uuid="31602cd8-4cfa-4912-a6fb-d731841f880c">my value</value>
               <value change="VX-16115" timestamp="2010-08-16T08:35:18.550+02:00" user="admin" uuid="cb47404c-5d69-466e-ad61-733b2cf8496b">my other value</value>
            </field>
            <field change="VX-16114" timestamp="2010-08-16T08:28:18.592+02:00" user="system" uuid="4cc88be0-4fc3-4243-a6e0-b1a151e6cde0">
               <name>shapeTag</name>
               <value change="VX-16114" timestamp="2010-08-16T08:28:18.592+02:00" user="system" uuid="b98a5553-a6ca-4235-bb14-fc17fdf7eda3">original</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>
HTML/XML

In order to modify either of the two values of the field the UUID must be specified, otherwise ambiguity will exist.

PUT /item/VX-250/metadata
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="-INF" end="+INF">
      <field>
         <name>field_a</name>
         <value>my new value</value>
      </field>
   </timespan>
</MetadataDocument>
NONE
400 An invalid parameter was entered
Context: metadata
Reason: Ambiguous path to value
NONE

Values can be removed by setting the mode attribute to remove.

PUT /item/VX-250/metadata
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="-INF" end="+INF">
      <field>
         <name>field_a</name>
         <value mode="remove" uuid="31602cd8-4cfa-4912-a6fb-d731841f880c"/>
      </field>
   </timespan>
</MetadataDocument>
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item>
      <metadata>
         <revision>VX-16114,VX-16115,VX-16117</revision>
         <timespan end="+INF" start="-INF">
            <field change="VX-16117" timestamp="2010-08-16T08:48:21.474+02:00" user="admin" uuid="d35fb0ea-cd05-4429-a707-b248420b3fe7">
               <name>field_a</name>
               <value change="VX-16115" timestamp="2010-08-16T08:35:18.550+02:00" user="admin" uuid="cb47404c-5d69-466e-ad61-733b2cf8496b">my other value</value>
            </field>
            <field change="VX-16114" timestamp="2010-08-16T08:28:18.592+02:00" user="system" uuid="4cc88be0-4fc3-4243-a6e0-b1a151e6cde0">
               <name>shapeTag</name>
               <value change="VX-16114" timestamp="2010-08-16T08:28:18.592+02:00" user="system" uuid="b98a5553-a6ca-4235-bb14-fc17fdf7eda3">original</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>
HTML/XML

Weak references

Groups and fields can refer to other groups and fields by using weak references. Furthermore the metadata of other items and collections as well as global metadata can be referenced.

Example: referencing global metadata

Adding some global metadata:

PUT /metadata
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <group mode="add">
      <name>test</name>
      <field>
        <name>example_name</name>
        <value>Global name</value>
      </field>
    </group>
  </timespan>
</MetadataDocument>
NONE
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <revision>VX-76,VX-82,VX-80,VX-84</revision>
  <timespan start="-INF" end="+INF">
    <group uuid="aaf7fde8-308d-4555-8a8b-8954f5ec5fd9" user="admin" timestamp="2010-12-27T09:40:32.667+01:00" change="VX-84">
      <name>test</name>
      <field uuid="376e831b-8e8e-4c0a-a7b2-dfdbb49d2e20" user="admin" timestamp="2010-12-27T09:40:32.667+01:00" change="VX-84">
        <name>example_name</name>
        <value uuid="431d8078-fb05-42f0-87ae-a9ea73b8c4d1" user="admin" timestamp="2010-12-27T09:40:32.667+01:00" change="VX-84">Global name</value>
      </field>
    </group>
  </timespan>
</MetadataDocument>
HTML/XML

Referencing it from an item:

PUT /item/VX-15/metadata
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <group mode="add">
      <name>test</name>
      <reference>aaf7fde8-308d-4555-8a8b-8954f5ec5fd9</reference>
    </group>
  </timespan>
</MetadataDocument>
NONE
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-15">
    <metadata>
      <revision>VX-86,VX-87</revision>
      <timespan end="+INF" start="-INF">
        <field change="VX-86" timestamp="2010-12-27T09:44:43.594+01:00" user="system" uuid="154c5b1c-575d-42f8-947d-5b0d38a78e96">
          <name>shapeTag</name>
          <value change="VX-86" timestamp="2010-12-27T09:44:43.594+01:00" user="system" uuid="eb05a782-75f1-4e42-9e5f-4d93be6f4247">original</value>
        </field>
        <group change="VX-87" timestamp="2010-12-27T09:45:21.786+01:00" user="admin" uuid="7c3d0b12-9b0a-48b8-b603-67fdcc26108d">
          <name>test</name>
          <referenced id="" type="global" uuid="aaf7fde8-308d-4555-8a8b-8954f5ec5fd9"/>
          <field change="VX-84" timestamp="2010-12-27T09:40:32.667+01:00" user="admin" uuid="376e831b-8e8e-4c0a-a7b2-dfdbb49d2e20">
            <name>example_name</name>
            <value change="VX-84" timestamp="2010-12-27T09:40:32.667+01:00" user="admin" uuid="431d8078-fb05-42f0-87ae-a9ea73b8c4d1">Global name</value>
          </field>
        </group>
      </timespan>
    </metadata>
  </item>
</MetadataListDocument>
HTML/XML

Metadata defined by the systems

Name

Description

user

The name of the user that imported the item. (Removed in 4.14, see below.)

title

The title of the item.

shapeTag

A shape tag that is used on a shape belonging to the item.

representativeThumbnail

A thumbnail that is representative of the item. Initially set by the system, but can be modified by a user.

representativeThumbnailNoAuth

Same as above, with the exception that no authentication is required.

itemId

The id of the item.

mediaType

The type of the media, e.g. video/audio/image/document/pdf/binary.

mimeType

The mime type of the media, e.g. image/jpeg.

created

The time when item was created.

startTimeCode

The start time of the item expressed as a time code.

startSeconds

The start time of the item expressed in seconds.

fieldValidationError

A error message that can be set if a metadata-field did not validate.

schemaValidationError

A error message that corresponds to what have failed during validation against a metadata-schema.

originalFilename

The original file name of the essence.

originalAudioCodec

The original audio codec of the essence.

originalVideoCodec

The original video codec of the essence.

originalHeight

The original height of the essence.

originalWidth

The original width of the essence.

originalFormat

The original container format of the essence.

durationSeconds

The duration of the item expressed in seconds.

durationTimeCode

The duration of the item expressed as a time code.

Deprecated since version 4.14: The system field user is not available any more, use the transient field __user instead. A transient field user ensures backwards compatibility for existing applications but will be removed in a future version.

Transient metadata

Transient metadata is a special type of metadata that is not revision controlled and only continuously updated by the system. It can be used to create complex search queries. All transient metadata are prefixed by double underscores.

Name

Description

Indexed

__user

The name of the user that imported the item. | Yes

__collection

The id of the collection an item belongs to. | Yes

__collection_size

The number of collections that the item belongs to.

Yes

__ancestor_collection

The id of an ancestor collection of an item.

Yes

__ancestor_collection_size

The number of ancestor collections of an item.

Yes

__shape

The id of a shape that belongs to the item.

Yes

__shape_size

The number of shapes that the item has.

Yes

__shape_last_added

The creation date of the newest shape of the item.

Yes

__shapetag_{tag}_hash[_{a}]

The checksum of a file of the item, where a is the algorithm.

Yes

__placeholder_shape_size

The number of placeholder shapes that the item has.

Yes

__version

The essence version numbers.

Yes

__version_count

The number of essence versions that the item has.

Yes

__storage

The id of a storage that has files that belongs to the item.

Yes

__storage_size

The number of storages that has files that belongs to the item.

Yes

__storage_{tag}

The id of a storage that has files that belongs to the item.

Yes

__storage_{tag}_size

The number of storages that has files that belongs to the item.

Yes

__storagegroup

The id of a group that has files that belongs to the item.

Yes

__storagegroup_size

The number of groups that has files that belongs to the item.

Yes

__sequence

The format of a sequence that belongs to the item.

Yes

__sequence_size

The number of sequences that the item has.

Yes

__metadata_last_modified

The time of the last metadata update.

Yes

__external_id

The external identifier assigned to the item.

Yes

__deletion_lock_id

The id of the effective deletion lock.

Yes

__deletion_lock_expiry

The expiration time of the effective deletion lock.

Yes

For collections, the following transient metadata fields exist:

Name

Description

Indexed

__user

The name of the user that imported the collection.

Yes

__child_collection

The id of the collection that the collection contains.

Yes

__child_collection_size

The number of collections that the collection contains.

Yes

__parent_collection

The id of the collection that the collection belongs to.

Yes

__parent_collection_size

The number of collections that the collection belongs to.

Yes

__ancestor_collection

The id of an ancestor collection of a collection.

Yes

__items_size

The number of direct item children.

Yes

__ancestor_collection_size

The number of ancestor collections of a collection.

Yes

__metadata_last_modified

The time of the last metadata update.

Yes

__folder_mapped

True if the collection maps to a folder, else false.

Yes

__child_folder_collection

The id of the folder collection that the collection contains.

Yes

__parent_folder_collection

The id of the folder collection that the collection belongs to.

Yes

__external_id

The external identifier assigned to the collection.

Yes

__deletion_lock_id

The id of the effective deletion lock.

Yes

__deletion_lock_expiry

The expiration time of the effective deletion lock.

Yes

Changed in version 4.15: The deletion lock transient metadata fields were added.

The transient field __user has been introduced and replaces the system field user. A transient field user ensures backwards compatibility for existing applications but will be removed in a future version.

File metadata

Metadata can be parsed from some file formats. The metadata is inserted as non-temporal metadata contained in different groups, depending on the source of the metadata. The exact structure of the groups may differ based on the encountered metadata. The parsing of file metadata must be enabled in the configuration.

Name

Type

Description

xmp_root

Group

The root group containing all XMP metadata.

document_root

Group

The root group for document metadata present in Office and PDF files.

document_text

Field

The text present in the document

document_metadata

Group

The group containing the metadata of the document.