Document metadata

Document metadata is similar to global metadata but instead of having a single, large global metadata document, it could be spread to multiple, small documents. This to reduce the size of the metadata and to improve performance.

Managing documents

List all documents

GET /document

Retrieves the list of metadata documents.

Query Parameters:
  • first (integer) – Return documents from that number in the document list. Default is 1.
  • number (integer) – Return at most that number of documents. Default is 100.
Produces:
  • application/xml, application/json – DocumentListDocument
Role:

_document_read

Example

GET /document

<?xml version="1.0" ?>
<DocumentListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <document>
        <name>producer</name>
        <uri>http://localhost:8080/API/document/producer</uri>
    </document>
    <document>
        <name>editor</name>
        <uri>http://localhost:8080/API/document/editor</uri>
    </document>
</DocumentListDocument>

Retrieve a document

GET /document/(name)

Retrieves the document with the specified name. This resource shares the same query parameters as the item metadata resource.

Query Parameters:
  • interval (string) –

    Comma-separated list

    • time-span - Filter out metadata, return only metadata for specified time span.
    • generic - Return all non-timed metadata.
    • all (default) - Return all metadata, same as interval=generic,-INF-+INF
    • result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.)
  • field (string) –

    Comma-separated list.

    • field-name - Return specified field.
    • field-name ”:” new-name - Return specified field, renamed to a new name in return value.
    • “-” field-name - Exclude specified field.
    • (default) - Return all fields.
  • group (string) –

    Comma-separated list.

    • group-name - Return specified group.
    • group-name + - Return specified group and subgroups.
    • group-name : new-name - Return specified group, renamed to a new name in return value.
    • - group-name - Exclude specified group.
    • (default) - Return all groups.
  • track (string) –

    Comma-separated list.

    • track-type track-number - Return metadata for specified track. Example of track is A2.
    • track-type t1 - t2 - Return metadata for specified track interval, e.g. A2-4.
    • track-type * - Return metadata for all tracks of specified type, e.g. A*.
    • generic - Return all non-tracked metadata.
    • all (default) - All metadata, with or without track specification, are returned.
  • language (string) –

    Comma-separated list.

    • language-tag - Return metadata for specific language, e.g. en_US. Wildcards may be used, e.g. *_CA for both Canadian French and Canadian English.
    • none - Return all metadata without language specification.
    • all (default) - Return all metadata, with or without language specification.
  • samplerate (string) – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
  • conflict (string) –
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • include (string) – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue (boolean) –
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
Produces:
Role:

_document_read

Example

GET /document/editor

<?xml version="1.0" ?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <revision>VX-20383</revision>
    <timespan end="+INF" start="-INF">
        <field change="VX-20383" timestamp="2014-11-18T10:29:45.166+01:00" user="admin" uuid="ff48980c-6431-4234-83ac-bd8d0af9462d">
            <name>editor_name</name>
            <value change="VX-20383" timestamp="2014-11-18T10:29:45.166+01:00" user="admin" uuid="5b9929ba-cce9-43eb-b63b-62a2426b9891">Bob</value>
        </field>
    </timespan>
</MetadataDocument>

Update or creates a document

PUT /document/(name)

Creates a new or modifies the existing document with the specified name.

Query Parameters:
  • revision (string) – The known revision. If not specified, the change set will attempt to override existing change sets.
  • skipForbidden (boolean) – Skip fields or groups that the user doesn’t have write access to. Default is false.
Accepts:
Produces:
Role:

_document_write

Example

PUT /document/editor

<?xml version="1.0" encoding="UTF-8"?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <field>
      <name>editor_name</name>
      <value>Bob</value>
    </field>
  </timespan>
</MetadataDocument>

Response:

<?xml version="1.0" ?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <revision>VX-20424</revision>
    <timespan end="+INF" start="-INF">
        <field change="VX-20424" timestamp="2014-11-18T13:36:46.130+01:00" user="admin" uuid="6279f922-621b-4f0a-b09c-41586736eb9e">
            <name>title</name>
            <value change="VX-20424" timestamp="2014-11-18T13:36:46.130+01:00" user="admin" uuid="0c662ed2-6623-45ac-9272-b6abc232488e">Bob</value>
        </field>
    </timespan>
</MetadataDocument>

Search for documents

PUT /document

Searches for documents matching a provided ItemSearchDocument.

Note that document indexing is disabled by default. Make sure to enable document indexing using indexDocumentMetadata and trigger a reindex so that any existing documents are added to the index.

New in version 5.0.

Query Parameters:
  • first (integer) – Start returning results from this index. Default is 1.
  • number (integer) – Return at most this number of documents. Default is 100.
  • count (boolean) –
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
Accepts:
Produces:

View change sets

GET /document/(name)/changes

Retrieves all change sets that have been applied to the document.

Query Parameters:
  • change (string) – Retrieve a single change set.
  • first (integer) – Return change sets from that number in the list of sorted change sets. Default is 1.
  • number (integer) – Return at most that number of change sets. Default is all change sets.
Response Headers:
  • Link – Contains URLs to the previous, next, first and last pages.
Produces:
Role:

_document_read

Example

GET /document/editor/changes

<?xml version="1.0" ?>
<MetadataChangeSetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <changeSet>
        <id>VX-20381</id>
        <metadata>
            <revision>VX-20380</revision>
            <timespan end="+INF" start="-INF">
                <field change="VX-20381" timestamp="2014-11-18T10:27:31.192+01:00" user="admin" uuid="7d1032a5-2ced-42ce-a553-1fbbaf2faeef">
                    <name>editor_name</name>
                    <value change="VX-20381" timestamp="2014-11-18T10:27:31.192+01:00" user="admin" uuid="c0426f6f-f1f0-4729-aaef-43a7f3b5bbfa">alice</value>
                </field>
            </timespan>
        </metadata>
    </changeSet>
    <changeSet>
        <id>VX-20382</id>
        <metadata>
            <revision>VX-20381</revision>
            <timespan end="+INF" start="-INF">
                <field change="VX-20382" timestamp="2014-11-18T10:27:31.229+01:00" user="admin" uuid="7d1032a5-2ced-42ce-a553-1fbbaf2faeef">
                    <name>editor_name</name>
                    <value change="VX-20382" timestamp="2014-11-18T10:27:31.229+01:00" user="admin" uuid="281d6f83-a624-4fa0-81fd-debe0e8bdf68">Bob</value>
                </field>
            </timespan>
        </metadata>
    </changeSet>
</MetadataChangeSetDocument>

Delete a document

DELETE /document/(name)

Removes the metadata document with the specified name.

Role:_document_write