Changes as highlighted during meeting on 2024/10/15

- removal of propertyTraits
- introduction of restoreMode
- document two restore scenarios for fixed/dynamic devices
- update relevant diagrams

APIs/schemas/bulkProperties-set-request.json

@@ -18,9 +18,9 @@
         "recurse": {
           "type": "boolean"
         },
-        "propertyTraits": {
-          "type": [ "array", "null" ],
-          "description": "Array of NcPropertyTrait items"
+        "restoreMode": {
+          "type": "integer",
+          "description": "numeric representation of NcRestoreMode enum options"
         }
       }
     }

APIs/schemas/bulkProperties-validate-request.json

@@ -18,9 +18,9 @@
         "recurse": {
           "type": "boolean"
         },
-        "propertyTraits": {
-          "type": [ "array", "null" ],
-          "description": "Array of NcPropertyTrait items"
+        "restoreMode": {
+          "type": "integer",
+          "description": "numeric representation of NcRestoreMode enum options"
         }
       }
     }

docs/API requests.md

@@ -105,8 +105,6 @@ The body of the request MUST include an object which includes the new value of t
 
 This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html#generic-getter-and-setter) on the specific object for the required property.
 
-`TBD`: Figure out how we map deprecation statuses for properties and methods.
-
 ### Setting bulk properties for a role path
 
 | ![Setting bulk properties](images/set-bulk-properties.png) |
@@ -116,7 +114,7 @@ This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms
 The PUT verb MUST be used for setting a bulk properties data set.
 
 The URL MUST target a specific role path.
-The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `propertyTraits` sub elements.
+The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `restoreMode` sub elements.
 
 ```json
 {
@@ -125,7 +123,7 @@ The body of the request MUST include an object which includes an `arguments` obj
             ...
         },
         "recurse": true,
-        "propertyTraits": null
+        "restoreMode": 1
     }
 }
 ```
@@ -167,8 +165,6 @@ The response MUST be of type [NcMethodResult](https://specs.amwa.tv/ms-05-02/lat
 
 This is equivalent to invoking the specified method.
 
-`TODO`: Figure out how we map deprecation statuses for properties and methods.
-
 ### Validating bulk properties for a role path
 
 | ![Validating bulk properties](images/validate-bulk-properties.png) |
@@ -178,7 +174,7 @@ This is equivalent to invoking the specified method.
 The PATCH verb MUST be used for validating a bulk properties data set.
 
 The URL MUST target a specific role path.
-The body of the request MUST include an object which includes an `arguments` object with `dataSet` and `recurse` sub elements.
+The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `restoreMode` sub elements.
 
 ```json
 {
@@ -187,7 +183,7 @@ The body of the request MUST include an object which includes an `arguments` obj
             ...
         },
         "recurse": true,
-        "propertyTraits": null
+        "restoreMode": 1
     }
 }
 ```

docs/Backup & restore.md

@@ -10,8 +10,9 @@ 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](#1-performing-a-backup)
-- Restoring a full backup data set to a device which is a [spare device replacing a faulty unit](#2-restoring-a-full-backup-data-set-to-a-device-which-is-a-spare-device-replacing-a-faulty-unit)
+- [Performing a backup](#performing-a-backup)
+- 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)
+- 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)
 
 `Note`: This does not mean that the backup & restore functionality can only be used in these scenarios.
 
@@ -41,12 +42,19 @@ A `modified backup` is a `full backup` or `partial backup` where the backup data
 
 ## General concepts
 
-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:
+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.
 
-- changing properties of existing objects
-- constructing new objects for blocks which require new members (structural changes)
-- deconstructing existing objects for blocks which need to have fewer members (structural changes)
-- reconstructing existing object (some devices might need to create an object again in order to apply properties which can only be changed at object construction). Reconstructed objects might have a different oid but MUST maintain their role within their parent block.
+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).
+
+A restore mode of `Rebuild` allows the changes performed through the `Modify` mode and allows the following additional ones:
+
+- 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)
+
+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.
 
 The general pattern for how devices interpret the restore workflow can be explained as follows:
 
@@ -55,10 +63,7 @@ The general pattern for how devices interpret the restore workflow can be explai
 - 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.
 
-Properties of a role path object within a backup data set will have specific traits described as [NcPropertyTrait](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertytrait).
-These traits are offered so that clients attempting to not restore all properties can use them to filter and only include in the restore workflow specific property traits. One example scenario is when a backup data set of a device is used to restore the state of existing device model objects but prevent any structural changes (creation or destruction of block members). To achieve this a client would exclude the `Structural` trait from the `propertyTraits` argument when [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).
-
-## 1. Performing a backup
+## 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).
 
@@ -72,11 +77,61 @@ Partial backups can be created by choosing other role paths. The scope of backup
 
 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.
 
-## 2. Restoring a full backup data set to a device which is a spare device replacing a faulty unit
+## Restoring a full backup data set to a fixed device after a faulty unit is replaced with an identical spare
+
+The following assumptions are made:
+
+- 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 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.
+
+In order to validate applying the whole 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 `Modify` in order to only allow changes to writeable properties)
+
+| ![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 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.
+
+In order to use the whole backup data set to restore 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 `Modify` in order to only allow changes to writeable properties)
 
-There is an assumption that the spare device replacing the faulty unit is the same product type from the same vendor.
+| ![Restoring a full backup](images/restoring-full-backup.png) |
+|:--:|
+| _**Restoring a full backup**_ |
 
-There is also an assumption that a [full backup](#1-performing-a-backup) has been created of the faulty unit when it was healthy.
+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.
+
+If devices require a system reboot in order to apply the restore then they 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.
+
+| ![Modify restore of spare](images/restoring_on_fixed_spare.png) |
+|:--:|
+| _**Modify restore of spare**_ |
+
+## Restoring a full backup data set to a dynamic device after a faulty unit is replaced with an identical spare
+
+The following assumptions are made:
+
+- 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 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.
 
@@ -86,7 +141,7 @@ The request body MUST include:
 
 - the backup dataSet
 - a boolean `recurse` argument (set to `true` for validating the whole device model)
-- a `propertyTraits` argument (set to `null` for including all properties regardless of their traits)
+- 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) |
 |:--:|
@@ -102,7 +157,7 @@ The request body MUST include:
 
 - the backup dataSet
 - a boolean `recurse` argument (set to `true` for validating the whole device model)
-- a `propertyTraits` argument (set to `null` for including all properties regardless of their traits)
+- 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) |
 |:--:|
@@ -111,3 +166,9 @@ The request body MUST include:
 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.
 
 If devices require a system reboot in order to apply the restore then they 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.
+
+| ![Rebuild restore of spare](images/restoring_on_dynamic_spare.png) |
+|:--:|
+| _**Rebuild restore of spare**_ |