Metadata fields

A metadata field is an ingredient of definition of the metadata set. Metadata fields define name and type of fields. Metadata fields can be organized into groups of fields. Furthermore fields can also be assigned additional data.

Access to fields can be restricted using access controls.

Managing metadata fields

Get list of fields

GET /metadata-field

Returns a list of all defined fields.

Query Parameters:
 
  • includeValues – Return the value enumeration for each field.
  • data – An optional comma-separated list of any additional data to include.
Produces:
Role:

_metadata_field_read

Get field definition

GET /metadata-field/(field-name)

Returns information about a specific metadata field definition.

Query Parameters:
 
  • includeValues – Return the value enumeration for this field.
  • data – An optional comma-separated list of any additional data to include.
Status Codes:
  • 404 Not found – The specified field could not be found.
Produces:
Role:

_metadata_field_read

Create or update field definition

PUT /metadata-field/(field-name)

Creates or updates a metadata field definition.

Status Codes:
  • 400 Bad request – Either the MetadataFieldDocument was not specified correctly or an illegal type was given.
Accepts:
Produces:
Role:

_metadata_field_write

Remove field definition

DELETE /metadata-field/(field-name)

Removes the metadata field definition. Note that this action may invalidate existing metadata.

Status Codes:
  • 200 OK – The field was deleted successfully.
  • 404 Not found – The field could not be found.
Role:

_metadata_field_write

Field value enumerations and validation

New in version 4.13.

It’s possible to get a list of allowed values based on the defined metadata dataset on the field.

Retrieve enumeration for field

GET /metadata-field/(field-name)/allowed-values

Returns the allowed values for a field based on the defined metadata dataset on the field.

Query Parameters:
 
  • constraint

    Optional, multiple query parameters can be specified. If no query parameters are specified, all the allowed values are returned.

    • field-name = value - Apply additinal constraint to the resulting value.

    Note that = is part of the query parameter, and has to be encoded (%3d).

Produces:

Example:

GET /metadata-field/rdf_city/allowed-values

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConstraintValueListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <value id="testNS:manchester1">Manchester</value>
  <value id="testNS:nyc1">New York City</value>
  <value id="vidi:gid7">Buffalo</value>
  <value id="vidi:gid1">Los Angeles</value>
  <value id="vidi:gid6">Rochester</value>
  <value id="testNS:london1">London</value>
  <value id="vidi:gid8">San Francisco</value>
</ConstraintValueListDocument>
GET /metadata-field/rdf_city/allowed-values?constraint=rdf_country=UK

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConstraintValueListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <value id="testNS:manchester1">Manchester</value>
  <value id="testNS:london1">London</value>
</ConstraintValueListDocument>

Retrieve enumeration for field with some constraints

POST /metadata-field/(field-name)/allowed-values

Returns the allowed values for a field based on the defined metadata dataset on the field.

Accepts:
Produces:

Example request:

POST /metadata-field/rdf_city/allowed-values
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MetadataFieldValueConstraintListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <constraint>
    <field>rdf_country</field>
    <value>USA</value>
  </constraint>
  <constraint>
    <field>rdf_state</field>
    <value>New York</value>
  </constraint>
</MetadataFieldValueConstraintListDocument>

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConstraintValueListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <value id="testNS:nyc1">New York City</value>
  <value id="vidi:gid7">Buffalo</value>
  <value id="vidi:gid6">Rochester</value>
</ConstraintValueListDocument>

Field value enumerations

Certain fields may have a restricted set of possible values, that a user should be able to select from for example. These value enumerations for a field can be stored in Vidispine.

Enumerations are made up out of a key and a value. The key is what should be stored in the metadata, while the value is the display name or description of the value.

Retrieve enumeration for field

GET /metadata-field/(field-name)/values

Retrieves the value enumeration for a specific field.

  • Only one of key-exact, key-start or key-regex can be set.
  • Only one of value-exact, value-start or value-regex can be set.
Query Parameters:
 
  • key-exact – Return the key with this name.
  • key-start – Return keys starting with this prefix.
  • key-regex – Return keys matching this regular expression.
  • value-exact – Return keys with this value.
  • value-start – Return keys with a value starting with this prefix.
  • value-regex – Return keys with a value matching this regular expression.
  • hits – The maximum number of keys to return. Default is all.
Produces:

Example

GET /metadata-field/document_language/values
<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>en</key>
    <value>English</value>
  </field>
  <field>
    <key>sv</key>
    <value>Swedish</value>
  </field>
</SimpleMetadataDocument>

Set enumeration for field

PUT /metadata-field/(field-name)/values

Sets the value enumeration for a specific field.

Accepts:

Example

PUT /metadata-field/document_language/values
<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>en</key>
    <value>English</value>
  </field>
  <field>
    <key>sv</key>
    <value>Swedish</value>
  </field>
</SimpleMetadataDocument>
200 OK

Field metadata

Metadata fields can be assigned additional data in a key-value fashion. This data can later be seen when retrieving metadata, using the include parameter in Get metadata.

Deprecated since version 4.1.2: Use the Key-value metadata interface instead.

Terse metadata schema

Retrieve terse metadata schema

GET /metadata-field/terse-schema

Retrieves the schema that defines terse metadata. This schema is dynamically generated based on the fields present in the system.

Produces:
  • application/xml – An XML schema.
Role:

_metadata_field_read

Viewing effective permissions

The merged access resource on fields and field groups can be used to check if a specific user is allowed to view, edit or delete specific fields or groups.

Retrieve user access to all fields

GET /metadata-field/merged-access/

Retrieves the permission for a specific user to all fields.

Query Parameters:
 
  • username – The name of the user to check.
Produces:
Role:

_accesscontrol_read

Example

GET /metadata-field/merged-access
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field username="admin">
    <name>collectionId</name>
    <permission>DELETE</permission>
  </field>
  <field username="admin">
    <name>itemId</name>
    <permission>DELETE</permission>
  </field>
  <field username="admin">
    <name>mediaType</name>
    <permission>DELETE</permission>
  </field>
  <field username="admin">
    <name>mrk_color</name>
    <permission>DELETE</permission>
  </field>
  ...
</AccessControlMergedDocument>

Retrieve user access to field

GET /metadata-field/(field-name)/merged-access/

Retrieves the permission for a specific user to a field.

Query Parameters:
 
  • username – The name of the user to check.
Produces:
Role:

_accesscontrol_read

Example

For a field without any access controls:

GET /metadata-field/title/access
<MetadataFieldAccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine"/>

We can see that the default, which is to allow full access to fields, is in effect:

GET /metadata-field/title/merged-access
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field username="admin">
    <name>title</name>
    <permission>DELETE</permission>
  </field>
</AccessControlMergedDocument>

Retrieve user access to all field groups

GET /metadata-field/field-group/merged-access/

Retrieves the permission for a specific user to all field groups and the field groups and fields part of those groups.

Query Parameters:
 
  • username – The name of the user to check.
Produces:
Role:

_accesscontrol_read

Example

GET /metadata-field/field-group/merged-access
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <fieldGroup username="admin">
    <name>facedetect_face</name>
    <permission>DELETE</permission>
    <field username="admin">
      <name>facedetect_pid</name>
      <permission>DELETE</permission>
    </field>
  </fieldGroup>
  ...
</AccessControlMergedDocument>

Retrieve user access to field group

GET /metadata-field/field-group/(group-name)/merged-access/

Retrieves the permission for a specific user to a field group and the field groups and fields part of that group.

Query Parameters:
 
  • username – The name of the user to check.
Produces:
Role:

_accesscontrol_read

Example

GET /metadata-field/field-group/mrk_marker/merged-access?username=test-user
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <fieldGroup username="test-user">
    <name>mrk_marker</name>
    <permission>DELETE</permission>
    <field username="test-user">
      <name>mrk_color</name>
      <permission>DELETE</permission>
    </field>
    <field username="test-user">
      <name>mrk_text</name>
      <permission>DELETE</permission>
    </field>
    <field username="test-user">
      <name>mrk_zerolength</name>
      <permission>DELETE</permission>
    </field>
  </fieldGroup>
</AccessControlMergedDocument>