Metadata fields [VC 21.3 GEN]

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

List all metadata fields

GET /metadata-field

Returns a list of all defined fields.

Query Parameters:	includeValues (boolean) – Return the value enumeration for each field. Default is `false`. data (string) – Comma-separated list of any additional data to include.
Produces:	application/xml, application/json – MetadataFieldListDocument text/plain – CRLF-delimited list of ids or URLs
Role:	_metadata_field_read

Retrieve a metadata field

GET /metadata-field/(field-name)

Returns information about a specific metadata field definition.

Query Parameters:	includeValues (boolean) – Return the value enumeration for this field. Default is `false`. data (string) – Comma-separated list of any additional data to include. Wildcard characters. e.g. ``, `myapp_`, `*_version` can be used. (New in 4.17.)
Status Codes:	404 Not found – The specified field could not be found.
Produces:	application/xml, application/json – MetadataFieldDocument
Role:	_metadata_field_read

Update or create a metadata field

PUT /metadata-field/(field-name)

Updates or creates a metadata field definition.

Status Codes:	400 Bad request – Either the MetadataFieldDocument was not specified correctly or an illegal type was given.
Accepts:	application/xml, application/json – MetadataFieldDocument
Produces:	application/xml, application/json – MetadataFieldDocument
Role:	_metadata_field_write

Delete a metadata field

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

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

Retrieve the enumeration for a 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 (string[]) – Multiple query parameters can be specified. If no query parameters are specified, all the allowed values are returned. field-name `=` value - Apply additional constraint to the resulting value. Note that `=` is part of the query parameter, and has to be encoded (`%3d`).
Produces:	application/xml, application/json – ConstraintValueListDocument

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 the enumeration for field given 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:	application/xml, application/json – MetadataFieldValueConstraintListDocument
Produces:	application/xml, application/json – ConstraintValueListDocument

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 the enumeration for a 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 (string) – Return the key with this name.
key-start (string) – Return keys starting with this prefix.
key-regex (string) – Return keys matching this regular expression.
value-exact (string) – Return keys with this value.
value-start (string) – Return keys with a value starting with this prefix.
value-regex (string) – Return keys with a value matching this regular expression.
hits (integer) – The maximum number of keys to return. Default is all.

Produces:

application/xml, application/json – SimpleMetadataDocument

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 the enumeration for a field

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

Sets the value enumeration for a specific field.

Accepts:

application/xml, application/json – SimpleMetadataDocument

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 Retrieve 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 (string) – The name of the user to check.
Produces:	application/xml, application/json – An AccessControlMergedDocument containing the fields, user and permissions.
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 (string) – The name of the user to check.
Produces:	application/xml, application/json – An AccessControlMergedDocument containing the field, user and permission.
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 (string) – The name of the user to check.
Produces:	application/xml, application/json – An AccessControlMergedDocument containing the group, its children, user and permission.
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 (string) – The name of the user to check.
Produces:	application/xml, application/json – An AccessControlMergedDocument containing the group, its children, user and permission.
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>