Content paths [VC 21.3 GEN]
Content paths are accepted by certain resources as a way of controlling the data that is returned for one or more entity.
Paths
A path consists of a list of keys that correspond to an field in the response. For example:
shape.containerComponent.format
shape.containerComponent.duration
shape.containerComponent.file.path
shape.containerComponent.file.size
Paths can also be written using a short-hand format:
shape.containerComponent.[format,duration]
shape.containerComponent.file.[path,size]
A path that selects from an element that represents a sequence will select on all elements in the sequence. This path selects the codec from all audio components for example:
shape.audioComponent.codec
Keys can contains a qualifier that further restricts the response:
shape[tag=original].containerComponent.[format,duration]
shape[tag=original].containerComponent.file.[path,size]
The syntax is:
path ::= key ( "." key )* key ::= identifier ("[" qualifier "]")* qualifier ::= identifier "=" identifier identifier ::= letter { letter | number }*
Example
Fetch all metadata fields and groups:
p=metadata.timespan.[field,group]
Fetch all metadata groups:
p=metadata.timespan.group
Fetch only “second level” groups:
p=metadata.timespan.group.group
Fetch the contents of a group called “test_group”:
p=metadata.timespan.group[name=test_group]
Fetch child metadata fields in a group called “test_group”:
p=metadata.timespan.group[name=test_group].field
Fetch only the name
and value
of metadata fields (excluding properties like uuid
, timestamp
, etc.):
p=metadata.timespan.field.[name,value].value
Aliases
Aliases can be used to shorten long path strings and to refer to multiple paths at once. Aliases can have arguments, making them similar to macros in other programming languages.
alias ::= name [ "(" arg ("," arg)* ")" ] "=" path ("," path)* name ::= letter { letter | number }* arg ::= letter { letter | number }*
As with fields and configuration properties, prefer to prefix alias names with a unique application prefix, to avoid possible conflicts in the future.
When an alias is evaluated, any arguments in the path, expressed as $arg
, will be replaced by the argument value. The resulting path string must be a valid path. For example, an alias that provides information about a shape:
detail(tag)=shape[tag=$tag].containerComponent.format,shape[tag=$tag].videoComponent.[codec,duration]
Configure aliases using the path alias configuration resource.
PUT /configuration/path-alias
Content-Type: application/xml
<PathAliasConfigurationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<alias>v(name)=metadata.timespan[start=-INF][end=+INF].field[name=$name].value.value</alias>
<alias>detail(tag)=shape[tag=$tag].containerComponent.format,shape[tag=$tag].videoComponent.[codec,duration]</alias>
</PathAliasConfigurationDocument>
Default aliases
- v(name)
-
metadata.timespan[start=-INF][end=+INF].field[name=$name].value.value
Transient metadata will not be returned using content paths, unless explicitly specified in the path. For example, metadata
or metadata.timespan
give no transident field. And pathes like v(transient_field)
should be used for transient fields to be returned.