Document toolboxDocument toolbox

Vidispine

Metadata reference [VC 21.3.1 GEN]

Owned by Andreas Schmidt
Oct 05, 2021
23 min read

This page describes metadata related resources for item and collection.

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

  • /item

  • /collection

Get metadata for an entity

Retrieve 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 query 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.

Query Parameters:

  • projection (string) –

    (only supported in item metadata)

    Return metadata set according to projection. Default is default.

  • interval (string) –

    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

    • result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.)

  • starttc (boolean) –

    • true - Interval is given relative to start timecode of item.

    • false (default) - Interval is 0-based.

  • field (string) –

    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 (string) –

    Comma-separated list.

    • group-name - Return specified group.

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

    • 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 (string) –

    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 (string) –

    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 (string) –

    • yes (default) - Include all metadata conflicts, unresolved.

    • no - Return conflicts resolved according to field rules.

  • samplerate (string) – 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 (string) – A change-set-id, retrieves metadata the way it looked at the given revision.

  • terse (string) –

    (only supported in item metadata)

    • yes - Return metadata in terse format

    • no (default) - Return metadata in verbose format

  • include (string) – Comma-separated list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.

  • defaultValue (boolean) –

    • true - For unset fields, return default values.

    • false (default) - Do not return default values.

  • from (string) –

    (only supported in item metadata)

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

  • to (string) –

    (only supported in item metadata)

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

  • includeConstraintValue (string) –

    Comma-separated list of fields whose “display value” should be retrieved from the metadata dataset.

    • all (default) - Return the “display value” of all fields.

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

  • includeTransientMetadata (boolean) –

    • 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

Create 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 (string) – The known revision. If not specified, the change set will attempt to override existing change sets.

  • skipForbidden (boolean) – Skip fields or groups that the user doesn’t have write access to. Default is false

  • projection (string) –

    (only supported in item metadata)

    Sets metadata set according to projection. Default is default

  • output-projection (string) –

    (only supported in item metadata)

    Returns metadata according to projection. Default is default

  • onlyReturnChanges (boolean) –

    New in version 4.16.6.

    • true - Only return the changed entries.

    • false (default) - Return the whole global metadata after the update.
Status Codes:

  • 400 – Invalid input.

  • 404 – Invalid id.
Accepts:

  • application/json, application/xml – MetadataDocument or according to specified projection
Produces:
Role:

_metadata_write

Move 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 (string) – The new start time code

  • end (string) – The new end time code

  • uuid (string) – Required. 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>

List all change sets

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

Retrieves change sets that have been applied to the metadata.

Query Parameters:

  • change (string) – Retrieve a single change set.

  • first (integer) – Return change sets from that number in the list of sorted change sets. Default is 1.

  • number (integer) – Return at most that number of change sets. Default is 0 (all change sets).

  • interval (string) –

    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

    • result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.)

  • starttc (boolean) –

    • true - Interval is given relative to start timecode of item.

    • false (default) - Interval is 0-based.

  • field (string) –

    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 (string) –

    Comma-separated list.

    • group-name - Return specified group.

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

    • 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 (string) –

    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 (string) –

    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 (string) –

    • yes (default) - Include all metadata conflicts, unresolved.

    • no - Return conflicts resolved according to field rules.

  • samplerate (string) – 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.

  • include (string) – Comma-separated list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.

  • defaultValue (boolean) –

    • true - For unset fields, return default values.

    • false (default) - Do not return default values.

  • from (string) –

    (only supported in item metadata)

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

  • to (string) –

    (only supported in item metadata)

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

  • includeConstraintValue (string) –

    Comma-separated list of fields whose “display value” should be retrieved from the metadata dataset.

    • all (default) - Return the “display value” of all fields.

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

  • includeTransientMetadata (boolean) –

    • true (default) - Include transient metadata.

    • false - Do not include transient metadata in response.
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>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>

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

Compare two change sets

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.

Parameters:

  • from-changeset-id (string) – The id of the change set to compare against. Use previous to compare with the preceding change set.
Query Parameters:

  • valuesByUuid (boolean) – If true (default) then field values will be compared by uuid, if false then by the value itself.

  • interval (string) –

    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

    • result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.)

  • field (string) –

    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 (string) –

    Comma-separated list.

    • group-name - Return specified group.

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

    • 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 (string) –

    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 (string) –

    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 (string) – 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 (string) –

    • yes (default) - Include all metadata conflicts, unresolved.

    • no - Return conflicts resolved according to field rules.

  • include (string) – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.

  • defaultValue (boolean) –

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

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

Update 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

Trim a change set

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

Trim multiple change sets

PUT {metadata-entity}/(entity-id)/metadata/changes/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="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>

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

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 multiple metadata entries

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

Retrieve the metadata graph

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

Shows fields and values and their history as a graph.

Query Parameters:

  • groupBy (string) –

    • change (default) - Group fields and values by change set.

    • none - Present fields and groups without any grouping.
Produces:

  • image/png –

Role:

_administrator

Retrieve the 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 (string) –

    • 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