Metadata

This page describes metadata related resources for item and collection.

In the following reference, {metadata-entity} is one of the following:

  • /item
  • /collection

Changed in version 4.5: Collections now support the metadata operations listed here.

Get metadata for an entity

Get metadata

GET {metadata-entity}/(entity-id)/metadata

Returns the metadata set for an entity. This means all metadata change sets, combined, and then filtered according to matrix parameters.

Conflicts are normally returned with all possible values. With conflict=no, a user interface may choose to receive only one value; i.e., automatic conflict resolution will be enforced. The conflict resolution is only applied to the returned XML document, not to metadata in database.

Matrix Parameters:
 
  • projection

    (only supported in item metadata)

    Return metadata set according to projection. Default projection is default.

  • interval

    Comma-separated list

    • time-span - Filter out metadata, return only metadata for specified time span.
    • generic - Return all non-timed metadata.
    • all (default) - Return all metadata, same as interval=generic,-INF-+INF
  • starttc
    • true - Interval is given relative to start timecode of item.
    • false (default) - Interval is 0-based.
  • field

    Comma-separated list.

    • field-name - Return specified field.
    • field-name ”:” new-name - Return specified field, renamed to a new name in return value.
    • “-” field-name - Exclude specified field.
    • (default) - Return all fields.
  • group

    Comma-separated list.

    • group-name - Return specified group.
    • group-name + - Return specified group and subgroups.

      New in version 4.1.

    • group-name : new-name - Return specified group, renamed to a new name in return value.
    • - group-name - Exclude specified group.
    • (default) - Return all groups.
  • track

    Comma separated list.

    • track-type track-number - Return metadata for specified track. Example of track is A2.
    • track-type t1 - t2 - Return metadata for specified track interval, e.g. A2-4.
    • track-type * - Return metadata for all tracks of specified type, e.g. A*.
    • generic - Return all non-tracked metadata.
    • all (default) - All metadata, with or without track specification, are returned.
  • language

    Comma separated list.

    • language-tag - Return metadata for specific language, e.g. en_US. Wildcards may be used, e.g. *_CA for both Canadian French and Canadian English.
    • none - Return all metadata without language specification.
    • all (default) - Return all metadata, with or without language specification.
  • conflict
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • samplerate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
  • revision – A change-set-id, retrieves metadata the way it looked at the given revision.
  • terse

    (only supported in item metadata)

    • yes - Return metadata in terse format
    • no (default) - Return metadata in verbose format
  • include – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
  • from

    (only supported in item metadata)

    A timestamp value. Return metadata starting from the specific timestamp (inclusive)

  • to

    (only supported in item metadata)

    A timestamp value. Return metadata until the specific timestamp (non-inclusive)

  • includeConstraintValue

    Optional comma separated value, specifying a list of fields whose “display value” should be retrieved from the metadata dataset. (New in 4.13.)

    • all (default) - Return the “display value” of all fileds.
    • none - No “display value” will be returned. The fields will only have id set.
    • comma separated field names - Return the “display value” of the specified fields.
Query Parameters:
 
  • includeTransientMetadata
    • true (default) - Include transient metadata.
    • false - Do not include transient metadata in response.
Produces:
Role:

_metadata_read

Examples

GET /item/VX-7888/metadata;field=audio-comments:comment;track=A3;interval=40-60;samplerate=PAL;language=en
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item id="VX-7888">
        <metadata>
            <timespan start="1000/PAL" end="1250/PAL">
                <field>
                    <name>comment</name>
                    <value lang="en_US" user="joed" site="VY" timestamp="2009-10-11T11:36:30.330+02:00">Music</value>
                </field>
            </timespan>
            <timespan start="1250/PAL" end="1500/PAL">
                <field conflict="yes">
                    <name>comment</name>
                    <value lang="en_US" user="joed" site="VY" timestamp="2009-10-11T11:36:34.527+02:00">Congressman Smith</value>
                    <value lang="en_US" user="bigc" site="VX" timestamp="2009-10-11T11:32:30.330+02:00">Congressman Smythe</value>
                </field>
            </timespan>
        </metadata>
    </item>
</MetadataListDocument>
GET /item/VX-7888/metadata;track=A3;interval=1000/25-1500/25;conflict=no
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <metadata>
        <item id="VX-7888">
            <timespan start="1000/25" end="1250/25">
                <field>
                    <name>audio-comments</name>
                    <value lang="en_US" user="joed" site="VY" timestamp="2009-10-11T11:36:30.330+02:00">Music</value>
                    <value lang="sv_SE" user="karin" site="VS" timestamp="2009-10-11T14:11:14.888+02:00">Musik</value>
                </field>
            </timespan>
            <timespan start="1250/25" end="1500/25">
                <field conflict="yes">
                    <name>audio-comments</name>
                    <value lang="en_US" user="joed" site="VY" timestamp="2009-10-11T11:36:34.527+02:00">Congressman Smith</value>
                    <value lang="sv_SE" user="karin" site="VS" timestamp="2009-10-11T14:13:10.100+02:00">Kongressledamot Smith</value>
                </field>
            </timespan>
        </item>
    </metadata>
</MetadataListDocument>

Manipulating change sets

Add a metadata change set

PUT {metadata-entity}/(entity-id)/metadata

Sets the metadata for an entity, or, more specifically, creates a metadata change set for an entity.

The metadata change set binds to different intervals, tracks, and languages, which can be specified either in the URL or in the XML. Providing an empty timespan or an empty field will be interpreted as the removal of any existing element that matches. Fields specified by the system will not be removed by this action.

The revision can either be specified in the input XML/JSON or as a query parameter. If it is not set at all, it will attempt to override any existing values.

Query Parameters:
 
  • revision – The known revision. If not specified, the change set will attempt to override existing change sets.
  • skipForbidden – Skip fields or groups that the user doesn’t have write access to.
Matrix Parameters:
 
  • projection

    (only supported in item metadata)

    Sets metadata set according to projection. Default projection is default

  • output-projection

    (only supported in item metadata)

    Returns metadata according to projection. Default projection is default

Status Codes:
  • 400 – Invalid input.
  • 404 – Invalid id.
Accepts:
  • application/json, application/xmlMetadataDocument or according to specified projection
Produces:
Role:

_metadata_write

Moving metadata

PUT {metadata-entity}/(entity-id)/metadata/move

Moves the specified field or group from one timespan to another. There are some restrictions to this operation:

  1. Only top-level elements can be moved, i. e. no groups or fields that belongs to a group can be moved.
  2. All conflicts for the specified element must first be resolved before moving it.
  3. If moving a field, it cannot be set as sortable.
  4. If moving a field, it cannot be system specified.
Query Parameters:
 
  • start – The new start time code
  • end – The new end time code
  • uuid – The UUID of the element.
Status Codes:
  • 400 – Invalid input.
  • 404 – Invalid id.
Produces:
Role:

_metadata_write

Example

Retrieving the current metadata and checking the UUID of the top-level group element.

GET /item/VX-7620/metadata
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan end="18" start="17">
      <group change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="96635ac0-1242-496b-ae14-100de8934a2c">
         <name>myfieldgroup</name>
         <group change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="eada6004-7b7e-4000-8707-d6797ed27d72">
            <name>myfieldgroup</name>
            <field change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="03a37ea1-ab96-4c15-af6d-9a0efcac97f0">
               <name>title</name>
               <value change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="fa205556-f2cc-4456-8e54-075828e9da81">This is my title.</value>
            </field>
         </group>
      </group>
   </timespan>
</MetadataDocument>

Moving the top-level element to the timespan (-INF, +INF):

PUT /item/VX-7620/metadata/move?uuid=96635ac0-1242-496b-ae14-100de8934a2c&start=-INF&end=%2BINF
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan end="+INF" start="-INF">
      <group change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="96635ac0-1242-496b-ae14-100de8934a2c">
         <name>myfieldgroup</name>
         <group change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="eada6004-7b7e-4000-8707-d6797ed27d72">
            <name>myfieldgroup</name>
            <field change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="03a37ea1-ab96-4c15-af6d-9a0efcac97f0">
               <name>title</name>
               <value change="VX-16293" timestamp="2010-09-07T16:41:09.045+02:00" user="admin" uuid="fa205556-f2cc-4456-8e54-075828e9da81">This is my title.</value>
            </field>
         </group>
      </group>
   </timespan>
</MetadataDocument>

Viewing change sets

GET {metadata-entity}/(entity-id)/metadata/changes

Retrieves change sets that have been applied to the metadata.

Query Parameters:
 
  • change – An optional parameter to retrieve a single change set.
  • first – Optional integer. Return change sets from that number in the list of sorted change sets. Default is 1.
  • number – Optional integer. Return at most that number of change sets. Default is all change sets.
Status Codes:
  • 404 – Could not find the entity.
Response Headers:
 
  • Link – Contains URLs to the previous, next, first and last pages.
Produces:
Role:

_metadata_read

Example

GET item/VX-250/metadata/changes
<MetadataChangeSetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <changeSet>
    <id>VX-30</id>
    <metadata>
      <revision>VX-30</revision>
      <timespan start="-INF" end="+INF">
        <field>
          <name>durationSeconds</name>
          <value user="system" timestamp="2010-03-19T09:08:09.563+01:00" change="VX-30">232.32</value>
        </field>
        <field>
          <name>user</name>
          <value user="system" timestamp="2010-03-19T09:08:09.588+01:00" change="VX-30">admin</value>
        </field>
        <field>
          <name>durationTimeCode</name>
          <value user="system" timestamp="2010-03-19T09:08:09.576+01:00" change="VX-30">232320000@1000000</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
  <changeSet>
    <id>VX-31</id>
    <metadata>
      <revision>VX-31</revision>
      <timespan start="-INF" end="+INF">
        <field>
          <name>title</name>
          <value user="admin" timestamp="2010-03-19T09:16:25.454+01:00" change="VX-31">u1's title</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
  <changeSet>
    <id>VX-32</id>
    <metadata>
      <revision>VX-32</revision>
      <timespan start="-INF" end="+INF">
        <field>
          <name>title</name>
          <value user="admin" timestamp="2010-03-19T09:16:56.419+01:00" change="VX-32">u2's title</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
  <changeSet>
    <id>VX-33</id>
    <metadata>
      <revision>VX-33</revision>
      <timespan start="-INF" end="+INF">
        <field>
          <name>title</name>
          <value user="admin" timestamp="2010-03-19T09:21:28.692+01:00" change="VX-33">u1's and u2's title</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
</MetadataChangeSetDocument>

Viewing a specific change set

GET {metadata-entity}/(entity-id)/metadata/changes/(changeset-id)

Retrieves a specific change set.

Status Codes:
  • 404 – Could not find the entity or the change set.
Produces:
Role:

_metadata_read

Comparing change sets

New in version 4.0.

GET {metadata-entity}/(entity-id)/metadata/changes/(changeset-id)/compareTo/previous
GET {metadata-entity}/(entity-id)/metadata/changes/(changeset-id)/compareTo/(from-changeset-id)

Retrieves a metadata document containing the differences between the entity metadata as of revision changeset-id compared to the metadata as of revision from-changeset-id.

The mode attribute is used to indicate if a field, field group or value has been added or removed.

Note: This should be seen as a diff between the metadata as it was between the two revisions, meaning that for example fields or field groups that have been added and then removed in between will not be shown.

Query Parameters:
 
  • valuesByUuid – If true (default) then field values will be compared by uuid, if false then by the value itself.
Matrix Parameters:
 
  • interval

    Comma-separated list

    • time-span - Filter out metadata, return only metadata for specified time span.
    • generic - Return all non-timed metadata.
    • all (default) - Return all metadata, same as interval=generic,-INF-+INF
  • field

    Comma-separated list.

    • field-name - Return specified field.
    • field-name ”:” new-name - Return specified field, renamed to a new name in return value.
    • “-” field-name - Exclude specified field.
    • (default) - Return all fields.
  • group

    Comma-separated list.

    • group-name - Return specified group.
    • group-name + - Return specified group and subgroups.

      New in version 4.1.

    • group-name : new-name - Return specified group, renamed to a new name in return value.
    • - group-name - Exclude specified group.
    • (default) - Return all groups.
  • track

    Comma separated list.

    • track-type track-number - Return metadata for specified track. Example of track is A2.
    • track-type t1 - t2 - Return metadata for specified track interval, e.g. A2-4.
    • track-type * - Return metadata for all tracks of specified type, e.g. A*.
    • generic - Return all non-tracked metadata.
    • all (default) - All metadata, with or without track specification, are returned.
  • language

    Comma separated list.

    • language-tag - Return metadata for specific language, e.g. en_US. Wildcards may be used, e.g. *_CA for both Canadian French and Canadian English.
    • none - Return all metadata without language specification.
    • all (default) - Return all metadata, with or without language specification.
  • samplerate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
  • conflict
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • include – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
Status Codes:
  • 404 – Could not find the item.
Produces:
Role:

_metadata_read

Example

Retrieving the current metadata of the item:

GET item/VX-250/metadata/
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-12621">
      <metadata>
         <revision>VX-41277,VX-41278</revision>
         <timespan end="+INF" start="-INF">
            <field change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="6ddc9537-8c10-46ff-9ed8-5f12bedc589a">
               <name>itemId</name>
               <value change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="d26312bf-e240-4534-9695-670be5c7bb76">VX-12621</value>
            </field>
            <field change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="048ebf22-43b7-4979-abe0-8aa5c12363ad">
               <name>created</name>
               <value change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="8eeb6df4-92f4-4d94-96be-ad1b8dd7a06b">2013-04-17T13:20:44.512Z</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>

Set the item title:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="-INF" end="+INF">
      <field>
         <name>title</name>
         <value>New title</value>
      </field>
   </timespan>
</MetadataDocument>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item>
      <metadata>
         <revision>VX-41277,VX-41278,VX-41279</revision>
         <timespan end="+INF" start="-INF">
            <field change="VX-41279" timestamp="2013-04-17T15:24:00.907+02:00" user="admin" uuid="2332c696-b3c8-4a55-9d37-437043258411">
               <name>title</name>
                   <value change="VX-41279" timestamp="2013-04-17T15:24:00.907+02:00" user="admin" uuid="dd139c76-86cf-4826-9037-892c928818d9">New title</value>
            </field>
            <field change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="6ddc9537-8c10-46ff-9ed8-5f12bedc589a">
               <name>itemId</name>
               <value change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="d26312bf-e240-4534-9695-670be5c7bb76">VX-12621</value>
            </field>
            <field change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="048ebf22-43b7-4979-abe0-8aa5c12363ad">
               <name>created</name>
               <value change="VX-41277" timestamp="2013-04-17T15:20:44.686+02:00" user="system" uuid="8eeb6df4-92f4-4d94-96be-ad1b8dd7a06b">2013-04-17T13:20:44.512Z</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>

Retrieving the changes since the last update:

GET item/VX-250/metadata/changes/VX-41279/compareTo/previous
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="-INF" end="+INF">
      <field uuid="2332c696-b3c8-4a55-9d37-437043258411" user="admin" timestamp="2013-04-17T15:24:00.907+02:00" change="VX-41279" mode="add">
         <name>title</name>
         <value uuid="dd139c76-86cf-4826-9037-892c928818d9">New title</value>
      </field>
   </timespan>
</MetadataDocument>

Modifying a single change set

PUT {metadata-entity}/(entity-id)/metadata/changes/(changeset-id)

Replaces the contents of a change set with the specified id with the metadata given in the document.

Status Codes:
  • 404 – Could not find the item or the change set.
Accepts:
  • application/xml, application/json – A MetadataDocument containing the new version of the change set.
Produces:
  • application/xml, application/json – A MetadataDocument containing the metadata of the item.
Role:

_metadata_write

Example

Retrieving the current metadata of the item:

GET item/VX-250/metadata/
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-250">
      <metadata>
         <revision>VX-15930</revision>
         <timespan end="+INF" start="-INF">
               <name>durationSeconds</name>
               <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14.118</value>
            </field>
            <field>
               <name>durationTimeCode</name>
               <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14118000@1000000</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>

Inserting some metadata:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan end="8" start="5">
      <field>
         <name>title</name>
         <value lang="en_US">My title!</value>
      </field>
      <field>
         <name>my_field</name>
         <value lang="en_US">4</value>
      </field>
   </timespan>
</MetadataDocument>
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-250">
      <metadata>
         <revision>VX-15930,VX-15932</revision>
         <timespan end="+INF" start="-INF">
               <name>durationSeconds</name>
               <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14.118</value>
            </field>
            <field>
               <name>durationTimeCode</name>
               <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14118000@1000000</value>
            </field>
         </timespan>
         <timespan end="8" start="5">
            <field>
               <name>title</name>
               <value change="VX-15932" lang="en_US" timestamp="2010-07-02T10:39:31.170+02:00" user="admin">My title!</value>
            </field>
            <field>
               <name>my_field</name>
               <value change="VX-15932" lang="en_US" timestamp="2010-07-02T10:39:31.168+02:00" user="admin">4</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>

Modifying that change set:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan end="15" start="8">
      <field>
         <name>title</name>
         <value lang="en_US">My title!</value>
      </field>
   </timespan>
</MetadataDocument>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <revision>VX-15930,VX-15932</revision>
   <timespan end="+INF" start="-INF">
      <field>
         <name>durationSeconds</name>
         <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14.118</value>
      </field>
      <field>
         <name>durationTimeCode</name>
         <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14118000@1000000</value>
      </field>
      </timespan>
      <timespan end="15" start="8">
         <field>
            <name>title</name>
            <value change="VX-15932" lang="en_US" timestamp="2010-07-02T10:39:31.170+02:00" user="admin">My title!</value>
         </field>
      </timespan>
</MetadataDocument>

Modifying multiple change sets

PUT {metadata-entity}/(entity-id)/metadata/changes/

Replaces the metadata in the specified change sets with the given data.

Statuscode:

Could not find the entity or the change set.

Accepts:
Produces:
Role:

_metadata_write

Trimming change sets

New in version 4.2.5.

PUT {metadata-entity}/(entity-id)/metadata/changes/trim
PUT {metadata-entity}/(entity-id)/metadata/changes/(changeset-id)/trim

Removes fields and values from the change set(s) that did not result in an actual change of the metadata.

Note that if all fields of a change set are removed, then the change set will also be removed.

Status Codes:
  • 404 – Could not find the item or the change set.
Produces:
Role:

_metadata_write

Example

Given an item with multiple change sets for the same set of fields:

GET /item/VX-260/metadata/changes
<MetadataChangeSetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <changeSet>
    <id>VX-816670</id>
    <metadata>
      <revision/>
      <timespan start="-INF" end="+INF">
        <field uuid="0e6bb918-090a-4388-9a55-e039a0462a20" user="admin" timestamp="2015-02-19T18:24:51.234+01:00" change="VX-816670">
          <name>title</name>
          <value uuid="9b2b24a5-9426-4f10-a37c-6ec0de90b07e" user="admin" timestamp="2015-02-19T18:24:51.234+01:00" change="VX-816670">A</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
  <changeSet>
    <id>VX-816671</id>
      <metadata>
        <revision>VX-816669,VX-816670,VX-816668</revision>
        <timespan start="-INF" end="+INF">
          <field uuid="0e6bb918-090a-4388-9a55-e039a0462a20" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
            <name>title</name>
            <value uuid="b7d9a4ad-a564-4d03-abf5-280f5ad69658" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">B</value>
          </field>
        <field uuid="ea7a2b4a-c105-4cb0-a55b-dc0aa9457e82" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
          <name>created</name>
          <value uuid="35f3b25c-c4ca-48e7-865b-2918fa1d33e0" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">2015-02-19T17:24:50.262Z</value>
        </field>
        <field uuid="452c038e-b7c8-4076-be40-43210b07c004" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
          <name>mediaType</name>
          <value uuid="018a0d40-6a0b-4238-b37f-d20dd9720d3a" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">none</value>
        </field>
        <field uuid="57e830d5-e06c-47bd-9495-e0f5d78e0a99" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
          <name>itemId</name>
          <value uuid="5f1add70-1ff6-445f-a72d-e80e7734d399" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">VX-415819</value>
        </field>
        <field uuid="1e941d0a-8091-4a11-b83e-09ca2bffd51d" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
          <name>user</name>
          <value uuid="16ef4003-7ac2-4c56-bcbf-9b646aba86b2" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">admin</value>
        </field>
        <field uuid="66efebb4-fbb3-4b7a-8cac-fbb4f68e28e8" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
          <name>shapeTag</name>
          <value uuid="6402586c-a9dc-45f7-a676-b133fc38e7b3" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">original</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
</MetadataChangeSetDocument>

Trimming the change sets will then cause fields where the values are unchanged to be removed.

PUT /item/VX-260/metadata/changes/trim
<MetadataChangeSetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <changeSet>
    <id>VX-816670</id>
    <metadata>
      <revision/>
      <timespan start="-INF" end="+INF">
        <field uuid="0e6bb918-090a-4388-9a55-e039a0462a20" user="admin" timestamp="2015-02-19T18:24:51.234+01:00" change="VX-816670">
          <name>title</name>
          <value uuid="9b2b24a5-9426-4f10-a37c-6ec0de90b07e" user="admin" timestamp="2015-02-19T18:24:51.234+01:00" change="VX-816670">A</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>
  <changeSet>
    <id>VX-816671</id>
    <metadata>
      <revision>VX-816670</revision>
      <timespan start="-INF" end="+INF">
        <field uuid="0e6bb918-090a-4388-9a55-e039a0462a20" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">
          <name>title</name>
          <value uuid="b7d9a4ad-a564-4d03-abf5-280f5ad69658" user="admin" timestamp="2015-02-19T18:24:51.397+01:00" change="VX-816671">B</value>
        </field>
      </timespan>
    </metadata>
  </changeSet>

Deleting a change set

DELETE {metadata-entity}/(entity-id)/metadata/changes/(changeset-id)

Deletes an entire change set.

Status Codes:
  • 404 – Could not find the entity or the change set.
Produces:
  • application/xml, application/json – A MetadataDocument containing the metadata of the item.
Role:

_metadata_write

Example

Retrieving the current metadata:

GET /item/VX-250/metadata
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-250">
      <metadata>
         <revision>VX-15930,VX-15932</revision>
         <timespan end="+INF" start="-INF">
               <name>durationSeconds</name>
               <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14.118</value>
            </field>
            <field>
               <name>durationTimeCode</name>
               <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14118000@1000000</value>
            </field>
         </timespan>
         <timespan end="8" start="5">
            <field>
               <name>title</name>
               <value change="VX-15932" lang="en_US" timestamp="2010-07-02T10:39:31.170+02:00" user="admin">My title!</value>
            </field>
            <field>
               <name>my_field</name>
               <value change="VX-15932" lang="en_US" timestamp="2010-07-02T10:39:31.168+02:00" user="admin">4</value>
            </field>
         </timespan>
      </metadata>
   </item>
</MetadataListDocument>

Deleting the change set “VX-15932”:

DELETE /item/VX-250/metadata/changes/VX-15932
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <revision>VX-15930</revision>
   <timespan end="+INF" start="-INF">
      <field>
         <name>durationSeconds</name>
         <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14.118</value>
      </field>
      <field>
         <name>durationTimeCode</name>
         <value change="VX-15930" timestamp="2010-07-02T10:36:20.317+02:00" user="system">14118000@1000000</value>
      </field>
      </timespan>
</MetadataDocument>

Modifying metadata using metadata entries

Metadata can also be modified using a MetadataEntryDocument or a MetadataEntryListDocument. They reference existing fields/groups/values with UUID.

New in version 4.1.

Modify a metadata entry

PUT {metadata-entity}/(entity-id)/metadata/entry/(entry-uuid)

Modifies a specific metadata field/group/value by UUID.

Accepts:
Produces:
Role:

_metadata_write

Example

Assume we have item VX-10 with the following metadata:

<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-10">
    <metadata>
      <revision>VX-110,VX-109,VX-148</revision>
      <timespan end="+INF" start="-INF">
        <field change="VX-109" timestamp="2013-11-12T09:39:54.767+01:00" user="system" uuid="31514647-8cf8-4d74-b674-e5941e007e77">
          <name>created</name>
          <value change="VX-109" timestamp="2013-11-12T09:39:54.767+01:00" user="system" uuid="afeb8aae-093f-4679-a156-eccf6aa5ba63">2013-11-12T08:39:54.670Z</value>
        </field>
        <field change="VX-109" timestamp="2013-11-12T09:39:54.767+01:00" user="system" uuid="5ba7c8f1-d77b-45fb-a8ed-ceda1d794207">
          <name>itemId</name>
          <value change="VX-109" timestamp="2013-11-12T09:39:54.767+01:00" user="system" uuid="01934732-9c66-4c6d-90a1-f14b8d188612">VX-10</value>
        </field>
        <field change="VX-148" timestamp="2013-11-13T12:13:12.160+01:00" user="admin" uuid="fd59a9f0-fe18-4183-82cb-e11aa33ad4bd">
          <name>title</name>
          <value change="VX-148" timestamp="2013-11-13T12:13:12.160+01:00" user="admin" uuid="17d6bac2-56c4-4117-b0dd-da474912bc3c">my item's title</value>
        </field>
        <field change="VX-148" timestamp="2013-11-13T12:13:12.160+01:00" user="admin" uuid="e2e964d4-5376-47f0-83dd-f4e3663181d8">
          <name>item_tags</name>
          <value change="VX-148" timestamp="2013-11-13T12:13:12.160+01:00" user="admin" uuid="45588018-2c14-4627-a889-b71559f1a318">tag 1</value>
          <value change="VX-148" timestamp="2013-11-13T12:13:12.160+01:00" user="admin" uuid="a1054ba4-da2d-46bf-8a87-e11bda2df243">tag 2</value>
        </field>
      </timespan>
    </metadata>
  </item>
</MetadataListDocument>

And we want to change the title of this item’s metadata. Note that the UUID of the title value is 17d6bac2-56c4-4117-b0dd-da474912bc3c. We can then make the following request;

PUT /item/VX-10/metadata/entry/17d6bac2-56c4-4117-b0dd-da474912bc3c
Content-Type: application/xml

<MetadataEntryDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <value>my item's new title</value>
</MetadataEntryDocument>

If we instead want to replace the values in the item_tags field, we can make the following request:

PUT /item/VX-10/metadata/entry/e2e964d4-5376-47f0-83dd-f4e3663181d8
Content-Type: application/xml

<MetadataEntryDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>item_tags</name>
    <value>new tag 1</value>
    <value>new tag 2</value>
  </field>
</MetadataEntryDocument>

This works in a similar fashion for field groups too.

Modify several metadata entries in one request

PUT {metadata-entity}/(entity-id)/metadata/entry/

Modifies multiple metadata fields/groups/values by UUID.

Accepts:
Produces:
Role:

_metadata_write

Example

The above changes could be made in one request in the following way:

PUT /item/VX-10/metadata/entry
Content-Type: application/xml

<MetadataEntryListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <entry uuid="17d6bac2-56c4-4117-b0dd-da474912bc3c">
    <value>my item's new title</value>
  </entry>
  <entry uuid="e2e964d4-5376-47f0-83dd-f4e3663181d8">
    <field>
      <name>item_tags</name>
      <value>new tag 1</value>
      <value>new tag 2</value>
    </field>
  </entry>
</MetadataEntryListDocument>

Metadata visualization

Get metadata graph

GET {metadata-entity}/(entity-id)/metadata/graph

Shows fields and values and their history as a graph.

Query Parameters:
 
  • groupBy
    • change (default) - Group fields and values by change set.
    • none - Present fields and groups without any grouping.
Produces:
  • image/png
Role:

_administrator

Get metadata graph as dot file

GET {metadata-entity}/(entity-id)/metadata/graph/dot

Shows fields and values and their history in dot format, for further processing.

Query Parameters:
 
  • groupBy
    • change (default) - Group fields and values by change set.
    • none - Present fields and groups without any grouping.
Produces:
  • text/plain, text/vnd.graphviz
Role:

_administrator