amwa-tv / is-14

AMWA IS-14 NMOS Device Configuration Specification [Work In Progress]

[Work In Progress] AMWA NMOS Device Configuration Specification

This repository holds the source for this Specification, part of the family of Networked Media Open Specifications from the Advanced Media Workflow Association

What does it do?

Describes the specification for the NMOS Configuration API.

Why does it matter?

Sets out the rules and requirements for implementing the NMOS Device Configuration API in devices and controllers.

How does it work?

Describes a standard way of exposing MS-05-02 models when using an HTTP API.

Getting started

There is more information about the NMOS Specifications and their GitHub repos at https://specs.amwa.tv/nmos.

is-14's Issues

Review that set of traits is sufficient

I'm keen to check that the list of traits is flexible enough to deal with the various restore scenarios we might encounter. To explore that, here's a list of property types from one of our config files that we should assign traits to. If multiple types of data have the same trait, are there scenarios where we would want to restore some of the properties with that trait but not all of them? If so, do we need additional traits?

• User supplied device name

• User supplied asset number

• serial number

• software build information

• Active license file

• timezone

• SNMP settings including addresses

• Alarms

• List of included cards

• Ethernet interface settings

  • MAC addresses, num tx-packets, num rx-packets, speeds

• Stream data such as ip addresses, FEC

• User supplied stream label

• Streams statistics - last hour, last day, last week etc.

• SFP info

• Management IP interface (separate to media IP interfaces - DHCP? / Default gateway? etc)

• BCP-002-02 type information

• IS-13 type information

• IS-05 type values

• IS-04 UUID values

• NcBlock type information (lists of other objects)

Minimise need for clients to edit backup sets to perform everyday tasks

One thing I'm not too keen on is a client editing the backup set on a routine basis in order to satisfy everyday tasks (such as templating for bulk provisioning by removing addresses). This potentially requires the client to have detailed knowledge of each device and i don't think that moves us sufficiently on from where we are now.
You could argue that the vendor could provide the editing tool but that requires the vendor to maintain two pieces of software which I think they would prefer to avoid.

Success / error scenarios to check we've covered most behaviours

Here's a list of things that could happen during a restore operation. In the interests of thoroughness, I've listed things that should be normal in addition to error conditions. I think we should look at all of them to ensure we haven't missed anything.

To save typing I've used BDS to mean Backup Data Set and DM for Device's Device Model (as expressed by NcClassManager).

(Side question: Does the BDS include the NcClassManager and if so, what trait does it have?)

(Unlike IS-12, it seems that the primary way of identifying an object is via its role path but this does require use of oids. Therefore it seems like there should be a mapping process between the BDS set of oids and those in use on the device. If so, we need to describe that.)

The scenarios: What do we set in NcMethodResultObjectPropertiesSetValidation and/or NcObjectPropertiesSetValidation when...

• The BDS Vendor fingerprint is not compatible with the Device?

• The BDS includes a property in an NcObject the Device doesn't know about?

• The BDS is missing an optional DM property?

• The BDS is missing a mandatory DM property?

• The BDS has a property that is read-only?

• The type of a BDS property differs from the type in the DM?

• The traits of a BDS property differs from what the device thinks they should be?

• The value in the BDS is out of range?

• A property is a struct and the BDS has a field with a name not in the DM?

• A property is a struct and the BDS has a field with type that is different to that in the DM?

• A property is a struct and the BDS is missing a field that is optional?

• A property is a struct and the BDS is missing a field that is mandatory?

• The BDS has an NcObject with a role path that isn't listed in any NcBlock in the BDS? (Maybe a result of editing)

• The BDS lists a role in an NcBlock but there is no NcObject with that role path in the BDS or on the Device?

• The BDS lists a role in an NcBlock but there is no NcObject with that role path in the BDS but there is one on the Device?

• The BDS lists a role in an NcBlock but there is no NcObject with that role path on the Device but there is one in the BDS?

• The BDS lists more NcWorkers in a block than the Device can support?

• The BDS lists an oid that the Device has but the role names differ?

• Two NcBlocks list the same oid?

• Two NcObjects have the same oid?

• Two instances of NcObjectPropertiesHolder have the same role path?

• An NcBlock in the BDS lists an oid that is also listed in a NcBlock on the Device that has a different purpose?

• Multiple instances of the same manager are present in the BDS?

Other comments:

• It would be nice if NcMethodResultObjectPropertiesSetValidation included an overallStatus field

• Do attempts to write to read-only properties create an NcPropertyRestoreException?

• Should NcPropertyRestoreException have a 'severity' field (e.g. 'info' vs 'error')

• NcRestoreValidationStatus is per NcObject - How do we deal with properties that are OK

• isReadOnly in NcPropertyValueHolder shouldn't be nullable (unless null can be represented as absent)

API requests: have a single table mapping NcMethodStatus to HTTP codes

https://github.com/AMWA-TV/is-14/blob/publish-CR/docs/API%20requests.md

Currently there are multiple tables describing mappings from NcMethodStatus to HTTP codes. This should be replaced with a single table that maps all NcMethodStatus codes to HTTP codes (similar to the data type marshalling document)

RAML document

A RAML document is needed to be consistent with other interface specifications.

Data type marshalling: correct handling of 64 bit integers

https://github.com/AMWA-TV/is-14/blob/publish-CR/docs/Data%20type%20marshalling.md

JSON currently only supports integers with a maximum of 53 bits, and so handling of 64-bit integers needs to either be transmitted as text or split into two 32-bit integers and recombined.

This specification, and for that matter IS-12, needs to determine which work around is to be used.

Thoughts on traits selection in ValidateSetPropertiesByPath() and SetPropertiesByPath()

I suggest renaming includedPropertyTraits to propertyTraitsFilter and make it nullable (i.e. sequence<NcPropertyTrait>? propertyTraitsFilter).

Then describing propertyTraitsFilter as:

propertyTraitsFilter - If non-null, specifies that only role paths with the traits specified by this property are to be validated / restored. If the parameter is null, the operation should proceed as if this property was set to "General", "Structural", "InstanceSpecific", and "DeviceGenerated" thus invoking a full restore.

Overview: add context when linking to existing specs

The relationship between this specification and MS-05 should be more explicit.

Perhaps add a dedicated section for the relationship between this spec and others, that has a sentence along the lines of "IS-14 is an RESTful API for accessing MS-05 Device Models. This API will support the full set of MS-05 functionality apart from subscriptions and notifications".