APIs: Common Keys
←APIs · Index↑ · APIs - Client Side Implementation Notes→
A number of common keys are used within NMOS APIs. Their definitions, required practices for interpretation and permitted values are described below.
Version
Core resources such as Sources, Flows, Nodes etc. include a ‘version’ attribute. As properties of a given Flow or similar will change over its lifetime, the version identifies the instant at which this change took place. For example, if a vision mix transition occurred which resulted in a change to the ‘parents’ which make up a particular Flow, the ‘version’ should be modified to reflect the wall clock instant at which this change occurred.
The version is a nanosecond TAI timestamp represented as a string of the format: <seconds>:<nanoseconds>. Note the ‘:’ as opposed to a ‘.’, indicating that the value ‘1439299836:10’ should be interpreted as 1439299836 seconds and 10 nanoseconds.
Combining the version with the resource’s ID attribute creates a hash which can be used to uniquely identify a particular variant of a Source, Flow or similar.
Label
Freeform human readable string to be used within user interfaces.
Description
Freeform human readable string to be used within user interfaces.
Format
A URN describing the data format of a video, audio or data flow.
| Permitted Value | Valid From API Version |
|---|---|
| urn:x-nmos:format:video | v1.0 |
| urn:x-nmos:format:audio | v1.0 |
| urn:x-nmos:format:data | v1.0 |
| urn:x-nmos:format:mux | v1.1 |
See Use of URNs below for additional requirements regarding their handling.
Transport
A URN describing the protocol used to send data (video, audio, data etc.) over a network.
Note: From v1.3 onwards, permitted transport types are not versioned and are instead defined via the NMOS Parameter Registers. Prior to v1.3, the following table applies.
| Permitted Value | Valid From API Version |
|---|---|
| urn:x-nmos:transport:rtp | v1.0 |
| urn:x-nmos:transport:rtp.mcast | v1.0 |
| urn:x-nmos:transport:rtp.ucast | v1.0 |
| urn:x-nmos:transport:dash | v1.0 |
For example, an RTP Transmitter sending to a multicast group should use the transport ‘urn:x-nmos:transport:rtp.mcast’, but a receiver supporting both unicast and multicast should present the transport ‘urn:x-nmos:transport:rtp’ to indicate its less restrictive state.
See Use of URNs below for additional requirements regarding their handling.
Tags
A set of keys and values providing a means to filter resources based on particular categorisations. Each tag has a single key, but MAY have multiple values. Each tags SHOULD be interpreted using the comparison of a single key value pair, with the comparison being case-insensitive following the Unicode Simple Case Folding specification.
Example: Tags Format
{
"tags": {
"location": ["Salford", "Media City"],
"studio": ["HQ1"],
"recording": ["The Voice UK"]
}
}
Type (Devices)
A URN describing the role which a Device has within the production environment (such as camera, mixer, tally light etc.).
Note: From v1.3 onwards, permitted device types are not versioned and are instead defined via the NMOS Parameter Registers. Prior to v1.3, the following table applies.
| Permitted Value | Valid From API Version |
|---|---|
| urn:x-nmos:device:generic | v1.0 |
| urn:x-nmos:device:pipeline | v1.0 |
See Use of URNs below for additional requirements regarding their handling.
Use of URNs
All Uniform Resource Names (URNs) specified within the scope of the NMOS specifications MUST use the namespace ‘urn:x-nmos:’. Manufacturers MAY use their own namespaces to indicate values of URN which are not currently defined within the NMOS namespace.
Where a URN begins ‘urn:x-nmos:’ it MUST use the following construction:
- The URN ‘base’ is a sequence of one or more names delimited by ‘:’ characters, including the namespace
- The URN MAY include one or more ‘subclassifications’
- The URN MAY include a version number
Subclassifications are defined as the portion of the URN which follows the first occurrence of a ‘.’, but prior to any ‘/’ character. By convention, URNs which begin ‘urn:x-nmos:’ will never include a further ‘:’ after the first occurrence of a ‘.’.
For example, the URN base ‘urn:x-nmos:transport:rtp’ above has two subclassifications of ‘ucast’ and ‘mcast’.
API clients interpreting URNs MUST correctly recognise any as-yet undefined subclassifications as being associated with the URN base which appears prior to the first ‘.’ character.
For example, if filtering by the format ‘urn:x-nmos:format:video’, the filter is required to include any as-yet undefined subclassifications such as ‘urn:x-nmos:format:video.raw’.
Versions are defined as the portion of the URN which follows the first occurrence of a ‘/’, up to and including the remainder of the URN. Any ‘.’ characters after this point indicate a version delimiter. By convention, URNS which begin ‘urn:x-nmos:’ will format the version as ‘v<#MAJOR>.<#MINOR>’ and should be handled as specified in APIs.
For example, the URN ‘urn:x-nmos:control:sr-ctrl/v1.0’ can be separated into a base ‘urn:x-nmos:control:sr-ctrl’ and version ‘v1.0’.
Query API clients MUST be tolerant to URNs which have not yet been defined, but which may be added in later API versions.