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: - application/xml, application/json – MetadataFieldListDocument
- text/plain – CRLF-delimited list of ids or URLs
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: - application/xml, application/json – MetadataFieldDocument
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: - application/xml, application/json – MetadataFieldDocument
Produces: - application/xml, application/json – MetadataFieldDocument
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¶
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: - 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 enumeration for 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 Get metadata.
Deprecated since version 4.1.2: Use the Key-value metadata interface instead.
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: - 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 – 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 – 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 – 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>