Metadata

This page describes metadata related resources for item and collection.

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

Get metadata for an entity

Get metadata

GET /(entity-type)/(entity-id)/metadata

Returns the metadata set for an entity.

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)

  • include – A list of keys. Includes additional field specific data. See Field metadata. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue
    • true - For unset fields, return default values. See 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)

Query Parameters:
 
  • includeTransientMetadata
    • true (default) - Include transient metadata, see Transient metadata.
    • false - Do not include transient metadata in response.
Produces:
Role:

_metadata_read

Semantics

Returns the metadata set for an entity, see Identifiers. 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.

Examples

GET /item/VX-7888/metadata;field=audio-comments:comment;track=A3;interval=40-60;samplerate=PAL;language=en
<MetadataListDocument>
    <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>
    <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 /(entity-type)/(entity-id)/metadata

Sets the metadata for an entity.

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

MetadataDocument or according to specified projection

Produces:
  • application/xml, application/jsonMetadataDocument or according to specified outgoing projection
Role:

_metadata_write

Semantics

Sets the metadata for an entity (see Identifiers), 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.

Moving metadata

PUT /(entity-type)/(entity-id)/metadata/move
Query Parameters:
 
  • start – The new start Time codes
  • end – The new end Time codes
  • uuid – The UUID of the element.
Status Codes:
  • 400 – Invalid input.
  • 404 – Invalid id.
Produces:
Role:

_metadata_write

Semantics

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.

Example

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

GET /item/VX-7620/metadata
<MetadataDocument>
   <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>
   <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 /(entity-type)/(entity-id)/metadata/changes

Retrieves all change sets that have been applied to the metadata.

Query Parameters:
 
  • change – An optional parameter to retrieve a single change set.
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>

Comparing change sets

New in version 4.0.

GET /(entity-type)/(entity-id)/metadata/changes/(changeset-id)/compareTo/previous
GET /(entity-type)/(entity-id)/metadata/changes/(changeset-id)/compareTo/(from-changeset-id)
Query Parameters:
 
  • valuesByUuid – If true (default) then field values will be compared by uuid, if false then by the value itself.
Status Codes:
  • 404 – Could not find the item.
Produces:
Role:

_metadata_read

Semantics

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.

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 /(entity-type)/(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-xml-json-schema 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 /(entity-type)/(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 /(entity-type)/(entity-id)/metadata/changes/trim
PUT /(entity-type)/(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 /(entity-type)/(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

New in version 4.1.

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

Modify a metadata entry

PUT /(entity-type)/(entity-id)/metadata/entry/(entry-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

Several entries can be modified at once using a MetadataEntryListDocument.

PUT /(entity-type)/(entity-id)/metadata/entry/
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>