Document toolboxDocument toolbox

Vidispine

Examples [VC 21.3 GEN]

Owned by Andreas Schmidt
Aug 31, 2021
18 min read

Creating fields/groups, modifying and moving metadata

Let’s say that we have an item that contains a sports game. We want to record the goals that have occurred within the game. To do this we have the triple (time, team, player), where the time is the real-world time when the goal took place, the player that scored and the team the player plays for.

Creating the metadata fields

First to create the field for time, we choose the data type “date” since we want it to be indexed, but we will use it as temporal metadata so it is not applicable to be a sortable field.

PUT /metadata-field/sport_time
Content-Type: application/xml

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <type>date</type>
</MetadataFieldDocument>

As for creating the team and the player, we use the same reasoning above, with the exception of that we want a string instead

PUT /metadata-field/sport_team
Content-Type: application/xml

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <type>string</type>
</MetadataFieldDocument>
PUT /metadata-field/sport_player
Content-Type: application/xml

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <type>string</type>
</MetadataFieldDocument>

Creating the metadata field group

With the fields created we now want a way to group these fields together so we create a field group called “goal”.

PUT /metadata-field/field-group/goal

Now we simply add the fields, created above, to the group.

PUT /metadata-field/field-group/goal/sport_time
PUT /metadata-field/field-group/goal/sport_team
PUT /metadata-field/field-group/goal/sport_player

Retrieving the group:

GET /metadata-field/field-group/goal
<MetadataFieldListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <field sortable="false">
      <name>sport_time</name>
      <type>date</type>
   </field>
   <field sortable="false">
      <name>sport_player</name>
      <type>string</type>
   </field>
   <field sortable="false">
      <name>sport_team</name>
      <type>string</type>
   </field>
</MetadataFieldListDocument>

Modifying metadata

Let’s say that the item VX-7632 contains two goals that occurred during a game that matches the triples (time=’2010-09-05T16:20:33Z’, team=’Sweden’, player=’Pete’) and (time=’2010-09-05T16:42:05Z’, team=’Germany’, player=’Bob’). Within the item the first goal can be seen between the time codes (1200, 1380) and the second goal between the time codes (2700, 2940).

Each step will contain a diagram, where the dashed red line illustrates the semantics of the request being performed.

Adding the first goal

Adding the first goal without adding the player:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="1200" end="1380">
      <group mode="add">
         <name>goal</name>
         <field>
            <name>sport_time</name>
            <value>2010-09-05T16:20:33Z</value>
         </field>
         <field>
            <name>sport_team</name>
            <value>Sweden</value>
         </field>
      </group>
   </timespan>
</MetadataDocument>
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item id="VX-7632">
        <metadata>
            <revision>VX-16295,VX-16296,VX-16299</revision>
            <timespan end="1380" start="1200">
                <group change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="1f89d35d-02b6-4871-aa17-62c5ed4992f4">
                    <name>goal</name>
                    <field change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="915b6023-f374-4432-832c-a2c48c1efb56">
                        <name>sport_time</name>
                        <value change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="cce8f89a-a220-4e53-8734-5831a3a4eb77">2010-09-05T16:20:33Z</value>
                    </field>
                    <field change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="d9d9b21c-171d-402b-878d-cefa5b3f9727">
                        <name>sport_team</name>
                        <value change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="7493df98-be67-4fb6-97fe-a89b9e501207">Sweden</value>
                    </field>
                </group>
            </timespan>
            <timespan end="+INF" start="-INF">
                <field change="VX-16295" timestamp="2010-09-08T11:00:15.833+02:00" user="system" uuid="7c5c49f9-c740-4b0a-93e8-81490fb65799">
                    <name>shapeTag</name>
                    <value change="VX-16295" timestamp="2010-09-08T11:00:15.833+02:00" user="system" uuid="9c2945d5-3480-436e-bfbb-2444e586961d">original</value>
                </field>
            </timespan>
        </metadata>
    </item>
</MetadataListDocument>

Adding the second goal

Adding the second goal, accidentally to same timespan as the first goal:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="1200" end="1380">
      <group mode="add">
         <name>goal</name>
         <field>
            <name>sport_time</name>
            <value>2010-09-05T16:42:05Z</value>
         </field>
         <field>
            <name>sport_team</name>
            <value>Germany</value>
         </field>
         <field>
            <name>sport_player</name>
            <value>Bob</value>
         </field>
      </group>
   </timespan>
</MetadataDocument>
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item>
        <metadata>
            <revision>VX-16295,VX-16296,VX-16299,VX-16300</revision>
            <timespan end="1380" start="1200">
                <group change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="1f89d35d-02b6-4871-aa17-62c5ed4992f4">
                    <name>goal</name>
                    <field change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="915b6023-f374-4432-832c-a2c48c1efb56">
                        <name>sport_time</name>
                        <value change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="cce8f89a-a220-4e53-8734-5831a3a4eb77">2010-09-05T16:20:33Z</value>
                    </field>
                    <field change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="d9d9b21c-171d-402b-878d-cefa5b3f9727">
                        <name>sport_team</name>
                        <value change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="7493df98-be67-4fb6-97fe-a89b9e501207">Sweden</value>
                    </field>
                </group>
                <group change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="0e9a54eb-0b90-4ed9-ac68-d2cb5d7abc73">
                    <name>goal</name>
                    <field change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="4e5ffd77-ab59-46fe-9939-47ab61df7523">
                        <name>sport_team</name>
                        <value change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="2a64f141-b3aa-4686-973c-7c254a0b77cb">Germany</value>
                    </field>
                    <field change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="2444055e-40e0-49b6-8493-0f68df82f01a">
                        <name>sport_player</name>
                        <value change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="441404a4-882c-458a-af88-b2fad592d71c">Bob</value>
                    </field>
                    <field change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="01d54bbb-d01e-4c6f-880e-1c1cbc4e598e">
                        <name>sport_time</name>
                        <value change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="71dd57e3-4a39-41ad-b351-78c4bc20ac0b">2010-09-05T16:42:05Z</value>
                    </field>
                </group>
            </timespan>
            <timespan end="+INF" start="-INF">
                <field change="VX-16295" timestamp="2010-09-08T11:00:15.833+02:00" user="system" uuid="7c5c49f9-c740-4b0a-93e8-81490fb65799">
                    <name>shapeTag</name>
                    <value change="VX-16295" timestamp="2010-09-08T11:00:15.833+02:00" user="system" uuid="9c2945d5-3480-436e-bfbb-2444e586961d">original</value>
                </field>
            </timespan>
        </metadata>
    </item>
</MetadataListDocument>

Modifying the first goal

Adding the missing player to first goal:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="1200" end="1380">
      <group uuid="1f89d35d-02b6-4871-aa17-62c5ed4992f4">
         <name>goal</name>
         <field mode="add">
            <name>sport_player</name>
            <value>Pete</value>
         </field>
      </group>
   </timespan>
</MetadataDocument>
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item>
        <metadata>
            <revision>VX-16301,VX-16295,VX-16296,VX-16299,VX-16300</revision>
            <timespan end="1380" start="1200">
                <group change="VX-16301" timestamp="2010-09-08T15:41:22.212+02:00" user="admin" uuid="1f89d35d-02b6-4871-aa17-62c5ed4992f4">
                    <name>goal</name>
                    <field change="VX-16301" timestamp="2010-09-08T15:41:22.212+02:00" user="admin" uuid="e374df6f-deb5-4d5e-bfea-d1c2ae6df9aa">
                        <name>sport_player</name>
                        <value change="VX-16301" timestamp="2010-09-08T15:41:22.212+02:00" user="admin" uuid="dbb77bcb-c3e5-4d9e-90a6-3114eca1d091">Pete</value>
                    </field>
                    <field change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="915b6023-f374-4432-832c-a2c48c1efb56">
                        <name>sport_time</name>
                        <value change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="cce8f89a-a220-4e53-8734-5831a3a4eb77">2010-09-05T16:20:33Z</value>
                    </field>
                    <field change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="d9d9b21c-171d-402b-878d-cefa5b3f9727">
                        <name>sport_team</name>
                        <value change="VX-16299" timestamp="2010-09-08T15:36:01.836+02:00" user="admin" uuid="7493df98-be67-4fb6-97fe-a89b9e501207">Sweden</value>
                    </field>
                </group>
                <group change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="0e9a54eb-0b90-4ed9-ac68-d2cb5d7abc73">
                    <name>goal</name>
                    <field change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="4e5ffd77-ab59-46fe-9939-47ab61df7523">
                        <name>sport_team</name>
                        <value change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="2a64f141-b3aa-4686-973c-7c254a0b77cb">Germany</value>
                    </field>
                    <field change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="2444055e-40e0-49b6-8493-0f68df82f01a">
                        <name>sport_player</name>
                        <value change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="441404a4-882c-458a-af88-b2fad592d71c">Bob</value>
                    </field>
                    <field change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="01d54bbb-d01e-4c6f-880e-1c1cbc4e598e">
                        <name>sport_time</name>
                        <value change="VX-16300" timestamp="2010-09-08T15:38:28.715+02:00" user="admin" uuid="71dd57e3-4a39-41ad-b351-78c4bc20ac0b">2010-09-05T16:42:05Z</value>
                    </field>
                </group>
            </timespan>
            <timespan end="+INF" start="-INF">
                <field change="VX-16295" timestamp="2010-09-08T11:00:15.833+02:00" user="system" uuid="7c5c49f9-c740-4b0a-93e8-81490fb65799">
                    <name>shapeTag</name>
                    <value change="VX-16295" timestamp="2010-09-08T11:00:15.833+02:00" user="system" uuid="9c2945d5-3480-436e-bfbb-2444e586961d">original</value>
                </field>
            </timespan>
        </metadata>
    </item>
</MetadataListDocument>

Moving metadata

Since the second is placed in the wrong timespan it can be corrected by moving it.

PUT /item/VX-7632/metadata/move?start=2700&end=2940&uuid=0e9a54eb-0b90-4ed9-ac68-d2cb5d7abc73
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <revision>VX-16301,VX-16295,VX-16296,VX-16299,VX-16300</revision>
    <timespan start="1200" end="1380">
        <group uuid="1f89d35d-02b6-4871-aa17-62c5ed4992f4" user="admin" timestamp="2010-09-08T15:41:22.212+02:00" change="VX-16301">
            <name>goal</name>
            <field uuid="e374df6f-deb5-4d5e-bfea-d1c2ae6df9aa" user="admin" timestamp="2010-09-08T15:41:22.212+02:00" change="VX-16301">
                <name>sport_player</name>
                <value uuid="dbb77bcb-c3e5-4d9e-90a6-3114eca1d091" user="admin" timestamp="2010-09-08T15:41:22.212+02:00" change="VX-16301">Pete</value>
            </field>
            <field uuid="915b6023-f374-4432-832c-a2c48c1efb56" user="admin" timestamp="2010-09-08T15:36:01.836+02:00" change="VX-16299">
                <name>sport_time</name>
                <value uuid="cce8f89a-a220-4e53-8734-5831a3a4eb77" user="admin" timestamp="2010-09-08T15:36:01.836+02:00" change="VX-16299">2010-09-05T16:20:33Z</value>
            </field>
            <field uuid="d9d9b21c-171d-402b-878d-cefa5b3f9727" user="admin" timestamp="2010-09-08T15:36:01.836+02:00" change="VX-16299">
                <name>sport_team</name>
                <value uuid="7493df98-be67-4fb6-97fe-a89b9e501207" user="admin" timestamp="2010-09-08T15:36:01.836+02:00" change="VX-16299">Sweden</value>
            </field>
        </group>
    </timespan>
    <timespan start="-INF" end="+INF">
        <field uuid="7c5c49f9-c740-4b0a-93e8-81490fb65799" user="system" timestamp="2010-09-08T11:00:15.833+02:00" change="VX-16295">
            <name>shapeTag</name>
            <value uuid="9c2945d5-3480-436e-bfbb-2444e586961d" user="system" timestamp="2010-09-08T11:00:15.833+02:00" change="VX-16295">original</value>
        </field>
    </timespan>
    <timespan start="2700" end="2940">
        <group uuid="0e9a54eb-0b90-4ed9-ac68-d2cb5d7abc73" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">
            <name>goal</name>
            <field uuid="4e5ffd77-ab59-46fe-9939-47ab61df7523" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">
                <name>sport_team</name>
                <value uuid="2a64f141-b3aa-4686-973c-7c254a0b77cb" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">Germany</value>
            </field>
            <field uuid="2444055e-40e0-49b6-8493-0f68df82f01a" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">
                <name>sport_player</name>
                <value uuid="441404a4-882c-458a-af88-b2fad592d71c" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">Bob</value>
            </field>
            <field uuid="01d54bbb-d01e-4c6f-880e-1c1cbc4e598e" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">
                <name>sport_time</name>
                <value uuid="71dd57e3-4a39-41ad-b351-78c4bc20ac0b" user="admin" timestamp="2010-09-08T15:38:28.715+02:00" change="VX-16300">2010-09-05T16:42:05Z</value>
            </field>
        </group>
    </timespan>
</MetadataDocument>

The metadata has now been corrected and contain the information that we wanted to record.

Defining a metadata schema

Based on the types in the metadata example we can specify a schema. There is no restriction in creating a Metadata Schema with different field-groups that contain same metadata-fields.

PUT /metadata-schema
Content-Type: application/xml

<MetadataSchemaDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <!-- The organization is optional and can exist [0,n] outside of groups -->
    <group name="organization" min="0" max="-1">
        <!-- An organization has one or more employees -->
        <group name="employee" min="1" max="-1" reference="false"/>
        <!-- An organization has zero or more projects -->
        <group name="project" min="0" max="-1" reference="false"/>
        <!-- An organization has exactly one name -->
        <field name="example_name" min="1" max="1" reference="false"/>
    </group>

    <!-- A project cannot exist outside of a group -->
    <group name="project" min="0" max="0">
        <!-- A project has at least one employee, which has to be referenced -->
        <group name="employee" min="1" max="-1" reference="true"/>
        <!-- A project has exactly one name -->
        <field name="example_name" min="1" max="1" reference="false"/>
        <!-- A project has exactly one location element (it still can have more than one value) -->
        <field name="example_location" min="1" max="1" reference="false"/>
    </group>

    <!-- An employee cannot exist outside of a group -->
    <group name="employee" min="0" max="0">
        <!-- An employee has exactly one name -->
        <field name="example_name" min="1" max="1" reference="false"/>
        <!-- An employee might have a title -->
        <field name="example_title" min="0" max="1" reference="false"/>
    </group>
</MetadataSchemaDocument>

Retrieving the metadata of a new item:

GET /item/VX-11/metadata
<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-11">
    <metadata>
      <revision>VX-47</revision>
      <timespan end="+INF" start="-INF">
        <field change="VX-47" timestamp="2010-12-17T13:15:04.495+01:00" user="system" uuid="0f4ec1a0-8a5e-4b96-958a-b1ea7516e38a">
          <name>shapeTag</name>
          <value change="VX-47" timestamp="2010-12-17T13:15:04.495+01:00" user="system" uuid="99a471ee-18fd-4440-a218-80a3df40b471">original</value>
        </field>
      </timespan>
    </metadata>
  </item>
</MetadataListDocument>

Validating it:

PUT /item/VX-11/metadata/validate
200 OK

Adding the organization in the example:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <group>
      <name>organization</name>
      <field>
        <name>example_name</name>
        <value>My organization</value>
      </field>
      <group>
        <name>employee</name>
        <field>
          <name>example_name</name>
          <value>Bob</value>
        </field>
        <field>
          <name>example_title</name>
          <value>CEO</value>
        </field>
      </group>
      <group uuid="A">
        <name>employee</name>
        <field>
          <name>example_name</name>
          <value>Pete</value>
        </field>
        <field>
          <name>example_title</name>
          <value>Director</value>
        </field>
      </group>
      <group uuid="B">
        <name>employee</name>
        <field>
          <name>example_name</name>
          <value>Andrew</value>
        </field>
        <field>
          <name>example_title</name>
          <value>Editor</value>
        </field>
      </group>
      <group>
        <name>project</name>
        <field>
          <name>example_name</name>
          <value>Movie project</value>
        </field>
        <field>
          <name>example_location</name>
          <value>London</value>
          <value>Berlin</value>
        </field>
        <group>
          <name>employee</name>
          <reference>A</reference>
        </group>
        <group>
          <name>employee</name>
          <reference>B</reference>
        </group>
      </group>
    </group>
  </timespan>
</MetadataDocument>
200 OK

Adding an employee without a name to the organization:

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

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <group>
      <name>organization</name>
      <group mode="add">
        <name>employee</name>
        <field>
          <name>example_title</name>
          <value>Developer</value>
        </field>
      </group>
    </group>
  </timespan>
</MetadataDocument>
HTTP/1.1 400 An invalid parameter was entered
Context: metadata-schema
Reason: Too few of member example_name in group organization: 0 vs 1

Alternate way of creating a schema

A schema can also be built when creating and modifying metadata field groups. To create the schema above, the following three requests can be made.

PUT /metadata-field/field-group/employee
Content-Type: application/xml

<MetadataFieldGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <schema min="0" max="0"/>
  <field>
    <name>example_name</name>
    <schema min="1" max="1" reference="false"/>
  </field>
  <field>
    <name>example_title</name>
    <schema min="0" max="1" reference="false"/>
  </field>
</MetadataFieldGroupDocument>
PUT /metadata-field/field-group/project
Content-Type: application/xml

<MetadataFieldGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <schema min="0" max="0"/>
  <field>
    <name>example_name</name>
    <schema min="1" max="1" reference="false"/>
  </field>
  <field>
    <name>example_location</name>
    <schema min="1" max="1" reference="false"/>
  </field>
  <group>
    <name>employee</name>
    <schema min="1" max="-1" reference="true"/>
  </group>
</MetadataFieldGroupDocument>
PUT /metadata-field/field-group/organization
Content-Type: application/xml

<MetadataFieldGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <schema min="0" max="-1"/>
  <field>
    <name>example_name</name>
    <schema min="1" max="1" reference="false"/>
  </field>
  <group>
    <name>employee</name>
    <schema min="1" max="-1" reference="false"/>
  </group>
  <group>
    <name>project</name>
    <schema min="0" max="-1" reference="false"/>
  </group>
</MetadataFieldGroupDocument>