Item metadata [VC 21.3.1 GEN]

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>

HTTP/1.1 200 OK

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:

They can only exist within non-timed metadata.
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).
`float`	`maxInclusive`	A maximum allowed value (inclusive).
`integer`	`minInclusive`	A minimum allowed value (inclusive).
`integer`	`maxInclusive`	A maximum allowed value (inclusive).
`long`	`minInclusive`	A minimum allowed value (inclusive).
`long`	`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>

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>

HTTP/1.1 200 OK

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

<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-12">
    <metadata>
      <revision>VX-59,VX-60,VX-57</revision>
    </metadata>
  </item>
</MetadataListDocument>

GET /item/VX-12/metadata?field=testing_default&defaultValue=true HTTP/1.1

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

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>

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>

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>

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.

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

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

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>

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>

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

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

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>

Which results in:

GET item/VX-250/metadata

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

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

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

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>

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

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>

400 An invalid parameter was entered
Context: metadata
Reason: Ambiguous path to value

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>

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

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>

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

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>

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

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.