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

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>
NONE 
PUT /metadata-field/sport_player
Content-Type: application/xml

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

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
NONE

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

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

Retrieving the group:

GET /metadata-field/field-group/goal
NONE 
<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>
HTML/XML

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>
NONE 
<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>
HTML/XML

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>
NONE 
<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>
HTML/XML

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>
NONE 
<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>
HTML/XML

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

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

Retrieving the metadata of a new item:

GET /item/VX-11/metadata
NONE 
<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>
HTML/XML

Validating it:

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

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>
NONE 
200 OK
NONE

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

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