diff --git a/APIs/ConfigurationAPI.raml b/APIs/ConfigurationAPI.raml index c017e41..dd8fdf2 100644 --- a/APIs/ConfigurationAPI.raml +++ b/APIs/ConfigurationAPI.raml @@ -27,7 +27,7 @@ documentation: /rolePaths: displayName: 'Role Paths' get: - description: 'Returns the Role Paths of the Device Model. Each rolePath MUST be created by appending NcObject roles starting with the root block and using "." as the delimiter' + description: 'Returns the Role Paths of the Device Model. Each rolePath is created by appending NcObject roles starting with the root block and using "." as the delimiter' responses: 200: body: @@ -89,7 +89,7 @@ documentation: /descriptor: displayName: 'Class Descriptor' get: - description: 'Get MS-05 Class Descriptor of this object. This descriptor MUST include all inherited elements' + description: 'Get MS-05 Class Descriptor of this object. This descriptor includes all inherited elements' responses: 200: body: @@ -102,7 +102,7 @@ documentation: /methods: displayName: 'Methods' get: - description: 'Get Methods of this object. This response MUST include all object methods including all the inherited methods' + description: 'Get Methods of this object. This response includes all object methods including all the inherited methods' responses: 200: body: @@ -143,7 +143,7 @@ documentation: /properties: displayName: 'Properties' get: - description: 'Get Properties of the object. This response MUST include all object properties including all the inherited properties' + description: 'Get Properties of the object. This response includes all object properties including all the inherited properties' responses: 200: body: diff --git a/APIs/schemas/method-patch-request.json b/APIs/schemas/method-patch-request.json index 42e2535..ecf42c2 100644 --- a/APIs/schemas/method-patch-request.json +++ b/APIs/schemas/method-patch-request.json @@ -9,7 +9,7 @@ "properties": { "arguments": { "type": "object", - "description": "Method arguments. Arguments are specified as nested properties inside this object and their types are dictated by the specific MS-05-02 model for the method targeted. For methods which do not have arguments defined the object MUST be an empty object." + "description": "Method arguments. Arguments are specified as nested properties inside this object and their types are dictated by the specific MS-05-02 model for the method targeted. For methods which do not have arguments defined the object is an empty object." } } } diff --git a/APIs/schemas/ms05-error.json b/APIs/schemas/ms05-error.json index 4eea45a..a7996e0 100644 --- a/APIs/schemas/ms05-error.json +++ b/APIs/schemas/ms05-error.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "description": "NcMethodResultError", - "title": "NcMethodResultError" + "description": "Object of type NcMethodResultError or a type derived from NcMethodResultError", + "title": "Request error" } diff --git a/docs/APIs.md b/docs/APIs.md index d409ea9..c2da45c 100644 --- a/docs/APIs.md +++ b/docs/APIs.md @@ -57,8 +57,8 @@ Human-readable information can be provided, for example, via the IS-04 Device `l All public APIs are versioned as follows: * Requesting the API base resource (such as http(s)://<ip address or hostname>:<port>/x-nmos/configuration/) will provide a list containing the versions of the API present on the Node. -* A versioned API response must include only resources which match the schema for that API version. -* Data which is held for mismatched minor API versions may be returned if it can be conformed to the correct schema (see example below). Data must never be conformed between major API versions. +* A versioned API response MUST include only resources which match the schema for that API version. +* Data which is held for mismatched minor API versions may be returned if it can be conformed to the correct schema (see example below). Data MUST never be conformed between major API versions. #### Versioning Example @@ -107,4 +107,4 @@ In order to overcome shortcomings in some common libraries, the following requir The NMOS APIs use HTTP status codes to indicate success, failure and other cases to clients as per [RFC 7231](https://tools.ietf.org/html/rfc7231) and related standards. Where the RAML specification of an API specifies explicit response codes it is expected that a client will handle these cases in a particular way. -As explicit handling of every possible HTTP response code is not expected, clients must instead implement more generic handling for ranges of response codes (1xx, 2xx, 3xx, 4xx and 5xx). +As explicit handling of every possible HTTP response code is not expected, clients MUST instead implement more generic handling for ranges of response codes (1xx, 2xx, 3xx, 4xx and 5xx). diff --git a/docs/Backup & restore.md b/docs/Backup & restore.md index a3ea71f..f741404 100644 --- a/docs/Backup & restore.md +++ b/docs/Backup & restore.md @@ -11,8 +11,8 @@ The [Configuration API](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/Confi These mechanisms are used for enabling backup and restore functionality and this section of the specification aims to cover the expectations, behaviour and requirements for the following scenarios: - [Performing a backup](#performing-a-backup) -- Restoring a full backup data set to a [dynamic device after a faulty unit is replaced with an identical spare](#restoring-a-full-backup-data-set-to-a-dynamic-device-after-a-faulty-unit-is-replaced-with-an-identical-spare) -- Restoring a full backup data set to a [fixed device after a faulty unit is replaced with an identical spare](#restoring-a-full-backup-data-set-to-a-fixed-device-after-a-faulty-unit-is-replaced-with-an-identical-spare) +- Performing a [Modify restore](#performing-a-modify-restore) +- Performing a [Rebuild restore](#performing-a-rebuild-restore) `Note`: This does not mean that the backup & restore functionality can only be used in these scenarios. @@ -42,32 +42,47 @@ A `modified backup` is a `full backup` or `partial backup` where the backup data ## General concepts -Role path objects within a backup data set contain a boolean property called `isRebuildable`. If the object is a non-block object `isRebuildable` means the object can be reconstructed (constructing a fresh object which can accept changes even to its readonly properties). If the object is a block, `isRebuildable` depicts it can be reconstructed as mentioned in the statement before but also that its members can be added or removed. When a parent block object is not rebuildable but a member child is rebuildable the implication is that the child cannot change its role within that block when being rebuilt through a restore. +Role path objects within a backup data set contain a boolean property called `isRebuildable`. +If the object is a non-block object `isRebuildable` means the object's readonly properties can be modified. +If the object is a block, `isRebuildable` determines it can be modified as mentioned before but also that its members can be added or removed (new instances of rebuildable objects can be created in a rebuildable parent block). +When a parent block object is not rebuildable but a member child is rebuildable the implication is that the child cannot change its role within that block when being rebuilt through a restore. +Members of a rebuildable block which are not rebuildable cannot be removed. The restore mechanism achieved by [Setting bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) affects the device model by either rebuilding it or modifying it. -A restore mode of `Modify` MUST only be allowed to make changes to existing writeable properties of existing device model objects and cannot modify the device model in a structural way (cannot cause the addition or removal of objects from blocks). +Validating a restore operation before applying it is achieved by [Validating bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path). Implementations MUST perform the same checks and offer the same response as if the restore was being applied without actually performing changes to the device model objects. -A restore mode of `Rebuild` allows the changes performed through the `Modify` mode and allows the following additional ones: +A restore with the restore mode set to `Modify` MUST only be allowed to make changes to existing writeable properties of existing device model objects and MUST NOT modify the device model in a structural way (cannot cause the addition or removal of objects from blocks). Furthermore, devices are RECOMMENDED to evaluate a `Modify` restore (validate if the restore can happen) even when the backup data set contains readonly properties since writeable properties might result in the desired changes being applied and the readonly properties will result in notices in the response returned. -- adding new members to rebuildable block objects by constructing new member objects (structural changes) -- removing existing members from rebuildable block objects by deconstructing the member objects (structural changes) -- reconstructing existing objects (constructing fresh objects which can accept changes even to its readonly properties) +A restore with the restore mode set to `Rebuild` MUST allow the following actions: -In the interest of interoperability even devices with no `rebuildable` device model objects MUST accept `Rebuild` restores but only perform the changes in scope for a `Modify` restore whilst including notices for any changes to readonly properties. Furthermore, performing a `Modify` restore MUST be possible even when the backup data set contains readonly properties since writeable properties will results in the desired changes being applied and the readonly properties will result in notices in the response returned. +- make changes to existing writeable properties of existing device model objects +- add new members to rebuildable block objects by constructing new member objects (structural changes) +- remove existing members from rebuildable block objects by deconstructing the member objects (structural changes) +- reconstruct existing rebuildable objects (constructing fresh objects which can accept changes even to its readonly properties) -The general pattern for how devices interpret the restore workflow can be explained as follows: +`Rebuild` restores can perform structural changes against rebuildable device models in the following ways: -- devices MUST always offer healthy objects in the device model after a restore -- devices MUST attempt to use the backup data set provided first as a pool of information for changing/constructing/deconstructing/reconstructing a particular role path object and if they have all the necessary data they MUST report the restore status as `Ok`. -- if the backup data set provided doesn't have the information required for changing/constructing/deconstructing/reconstructing a particular role path object, but the device can fill in the necessary gaps from an internal knowledge store, then they MUST report the restore status as `Ok` and include properties which have benefited from internal knowledge store data in the [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) property as `Warning` notices. -- if devices cannot find the required information for changing/constructing/deconstructing/reconstructing a particular role path object in either the backup data set provided or an internal knowledge store then they MUST return `Failed` as the restore status. +- an object can be removed from a rebuildable block when the backup data set used in the restore offers a collection of members for the block which does not include the object (the success of this operation MAY depend on the internal constraints of the device - some devices might have have some members which cannot be removed or a minimum number of members). +- an object can be added to a rebuildable block when the backup data set used in the restore offers a collection of members for the block which includes the new object and also includes a new entry for the role path of the new object with its properties (the success of this operation MAY depend on the internal constraints of the device - devices are likely to check whether the new object class and role can be added to the block, whether they have all the necessary information to construct the new object, and might even check against a maximum number of members). + +In the interest of interoperability even devices with no `rebuildable` device model objects MUST accept `Rebuild` restores but only perform changes to writeable properties of device model objects whilst including notices for any other changes not supported by the device. + +The rules for devices implementing the restore workflow are: + +- after a restore operation devices MUST always contain valid objects (objects which have suitable values for each property within the current operating context) in their device models +- a restore operation modifying/rebuilding an object can use information from the backup data set provided or from an internal knowledge store +- a restore operation successfully modifying/rebuilding an object which uses only the backup data set information MUST report the validation restore status of the object as `Ok` +- a restore operation successfully modifying/rebuilding an object which uses internal knowledge store information MUST report the validation restore status of the object as `Ok` and list properties which have benefited from internal knowledge store data in the [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) property as `Warning` notices +- if devices cannot find the required information for modifying/rebuilding a particular object in either the backup data set provided or an internal knowledge store, then they MUST report the validation restore status of the object as `Failed` and also MUST populate the `statusMessage` property with details of why the operation failed. Devices MAY also populate [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) for the object properties which have contributed to the operation failing. +- a restore operation modifying/rebuilding an object resulting in at least one error [notice](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) MUST report the validation restore status of the object as `Failed` +- a restore operation modifying/rebuilding an object resulting only in warning [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) MUST report the validation restore status of the object as `Ok` ## Performing a backup Creating a backup is performed by using the `bulkProperties` endpoint of a device alongside the [Get verb](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#getting-all-the-properties-of-a-role-path). -In order to retrieve the whole device model (full backup), requests MUST use `root` as the `rolePath`. The response contains a `validationFingerprint` and the `values` of all the role paths in the device model. +In order to retrieve the whole device model (full backup), requests MUST use `root` as the `rolePath` and a `recurse` parameter with a value of `true`. The response contains a `validationFingerprint` and the `values` of all the role paths in the device model. | ![Performing a full backup](images/performing-full-backup.png) | |:--:| @@ -75,92 +90,72 @@ In order to retrieve the whole device model (full backup), requests MUST use `ro Partial backups can be created by choosing other role paths. The scope of backups can further be restricted by using a query parameter of `recurse=false` which will only include the properties of the targeted role path. -It is RECOMMENDED to store the backup file in its entirety and not remove elements from the data set as they might contain dependencies required by some of the role paths. +Devices are RECOMMENDED to populate `dependencyPaths` for objects which have dependencies on other role path objects when returning a backup data set ([see NcObjectPropertiesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncobjectpropertiesholder)). -## Restoring a full backup data set to a dynamic device after a faulty unit is replaced with an identical spare +Devices are RECOMMENDED to populate `allowedMembersClasses` for rebuildable blocks when returning a backup data set ([see NcObjectPropertiesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncobjectpropertiesholder)). This allows potential clients to determine which class ids can be used when modifying the members of these particular rebuildable blocks. -The following assumptions are made: +## Performing a Modify restore -- the spare device replacing the faulty unit is the same product type from the same vendor -- a [full backup](#performing-a-backup) has been created of the faulty unit when it was healthy -- the devices are dynamic containing rebuildable blocks and objects +The following sections describe how a `Modify` restore can be performed using a backup data set as detailed in [performing a backup](#performing-a-backup). -The first step is to perform a [Validation request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to check if the backup data set can be successfully restored. +Clients are RECOMMENDED to [Validate the restore operation](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) before attempting to apply the changes. -In order to validate applying the whole backup data set against the device model, requests MUST use `root` as the `rolePath`. +In order to validate applying the full backup data set against the device model, requests MUST use `root` as the `rolePath`. The request body MUST include: -- the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) - -| ![Validating a full backup](images/validating-full-backup.png) | -|:--:| -| _**Validating a full backup**_ | - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the validation failed. When there are properties of role path objects which cannot be validated from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- the backup dataSet containing a collection of [NcObjectPropertiesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncobjectpropertiesholder) entries with unique role paths +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) -The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore the backup. +A restore operation is performed through a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore a backup data set. -In order to use the whole backup data set to restore against the device model, requests MUST use `root` as the `rolePath`. +In order to restore the full backup data set to the device model, the request MUST use `root` as the `rolePath`. The request body MUST include: -- the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) - -| ![Restoring a full backup](images/restoring-full-backup.png) | -|:--:| -| _**Restoring a full backup**_ | - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the restore failed. When there are properties of role path objects which cannot be restored from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- the backup dataSet containing a collection of [NcObjectPropertiesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncobjectpropertiesholder) entries with unique role paths +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) -If devices require a system reboot in order to apply the restore then they MUST perform this immediately after responding to the restore request. +If a device requires a system reboot in order to apply the restore then it MUST perform this immediately after responding to the restore request. -The diagram below captures how the `Rebuild` restore uses the backup data set to transition the spare device from its out of the box device model to a state of functionality identical to the original faulty device. +The diagram below captures how the `Modify` restore uses the backup data set to transition the device from its current device model to a changed state. -| ![Rebuild restore of spare](images/restoring_on_dynamic_spare.png) | +| ![Modify restore](images/modify-restore.png) | |:--:| -| _**Rebuild restore of spare**_ | +| _**Modify restore**_ | -## Restoring a full backup data set to a fixed device after a faulty unit is replaced with an identical spare +## Performing a Rebuild restore -The following assumptions are made: +Rebuild restores are the only way to make structural changes to a device model. Structural changes are only allowed for rebuildable blocks. -- the spare device replacing the faulty unit is the same product type from the same vendor -- a [full backup](#performing-a-backup) has been created of the faulty unit when it was healthy -- the devices are fixed containing no rebuildable blocks or objects +The following sections describe how a `Rebuild` restore can be performed using a backup data set as detailed in [performing a backup](#performing-a-backup). -The first step is to perform a [Validation request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to check if the backup data set can be successfully restored. +Clients are RECOMMENDED to [Validate the restore operation](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) before attempting to apply the changes. -In order to validate applying the whole backup data set against the device model, requests MUST use `root` as the `rolePath`. +In order to validate applying the full backup data set against the device model, the request MUST use `root` as the `rolePath`. The request body MUST include: -- the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the validation failed. When there are properties of role path objects which cannot be validated from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- the backup dataSet containing a collection of [NcObjectPropertiesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncobjectpropertiesholder) entries with unique role paths +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) -The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore the backup. +A restore operation is performed through a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore a backup data set. -In order to use the whole backup data set to restore against the device model, requests MUST use `root` as the `rolePath`. +In order to restore the full backup data set to the device model, requests MUST use `root` as the `rolePath`. The request body MUST include: -- the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the restore failed. When there are properties of role path objects which cannot be restored from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- the backup dataSet containing a collection of [NcObjectPropertiesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncobjectpropertiesholder) entries with unique role paths +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) -If devices require a system reboot in order to apply the restore then they MUST perform this immediately after responding to the restore request. +If a device requires a system reboot in order to apply the restore then it MUST perform this immediately after responding to the restore request. -The diagram below captures how the `Rebuild` restore uses the backup data set to transition the spare device from its out of the box device model to a state of functionality identical to the original faulty device. +The diagram below captures how the `Rebuild` restore uses the backup data set to transition the device from its current device model to a changed state. In this case the operation makes a structural change to the device model. -| ![Modify restore of spare](images/restoring_on_fixed_spare.png) | +| ![Rebuild restore](images/rebuild-restore.png) | |:--:| -| _**Modify restore of spare**_ | +| _**Rebuild restore**_ | diff --git a/docs/images/modify-restore.png b/docs/images/modify-restore.png new file mode 100644 index 0000000..8aee516 Binary files /dev/null and b/docs/images/modify-restore.png differ diff --git a/docs/images/rebuild-restore.png b/docs/images/rebuild-restore.png new file mode 100644 index 0000000..6bbfec3 Binary files /dev/null and b/docs/images/rebuild-restore.png differ diff --git a/docs/images/restoring_on_dynamic_spare.png b/docs/images/restoring_on_dynamic_spare.png deleted file mode 100644 index 6f8d088..0000000 Binary files a/docs/images/restoring_on_dynamic_spare.png and /dev/null differ diff --git a/docs/images/restoring_on_fixed_spare.png b/docs/images/restoring_on_fixed_spare.png deleted file mode 100644 index 13c2a7e..0000000 Binary files a/docs/images/restoring_on_fixed_spare.png and /dev/null differ diff --git a/docs/images/validating-full-backup.png b/docs/images/validating-full-backup.png deleted file mode 100644 index 51b99f3..0000000 Binary files a/docs/images/validating-full-backup.png and /dev/null differ