Update Backup & Restore

- better response examples in diagrams
- definition for software version

docs/Backup & restore.md

@@ -9,9 +9,11 @@ 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 backup on the [same unit and the same version](#2-restoring-same-unit-and-same-version)
-- Restoring a backup on the [same unit but different version](#3-restoring-same-unit-but-different-version)
-- Restoring a backup on a [different unit using the same version](#4-restoring-different-unit-using-the-same-version)
+- Restoring a backup on the [same unit and the same software version](#2-restoring-same-unit-and-same-software-version)
+- Restoring a backup on the [same unit but different software version](#3-restoring-same-unit-but-different-software-version)
+- Restoring a backup on a [different unit using the same software version](#4-restoring-different-unit-using-the-same-software-version)
+
+where `software version` means any combination of software that dictates the functionality of the device (this includes firmware).
 
 `Note`: This does not mean that the backup & restore functionality can only be used in these scenarios.
 
@@ -24,8 +26,7 @@ The `validationFingerprint` is a generic string field (format is implementation
 
 - Manufacturer key
 - Product key
-- Firmware version
-- Software version
+- Software versions
 - Backup response hash
 - Whether its a full device model backup or a subset
 
@@ -37,9 +38,7 @@ 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 same unit and same version
-
-// TBD: Do we need to define what we mean by version? (firmware version, software version, product version?)
+## 2. Restoring same unit and same software version
 
 Assuming a [full backup](#1-performing-a-backup) of the unit was created and is intended to be restored on the same unit with the same version then 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 can be successfully restored.
 
@@ -56,8 +55,6 @@ The request body MUST include:
 
 The response MUST include a collection of all target device model role paths with a validation `status` property. For role paths which have a `status` other than `Ok` the response MUST also include a `statusMessage` with details of why the validation failed.
 
-// TBD: Do we need to give more detailed examples of statuses and statusMessages?
-
 The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to restore the backup.
 
 In order to restore the whole device model (restoring a full backup), requests MUST use `root` as the `rolePath`.
@@ -74,24 +71,24 @@ The request body MUST include:
 
 The response MUST include a collection of all target device model role paths with a restore `status` property. For role paths which have a `status` other than `Ok` the response MUST also include a `statusMessage` with details of why the restore failed.
 
-// TBD: Do we need to give more detailed examples of statuses and statusMessages?
-
-A `full backup` performed on the same unit and restored on the same unit and same version MUST be supported by the device.
+A `full backup` performed on the same unit and restored on the same unit and same software version MUST be supported by the device.
 
 Devices MUST allow the partial restoration of backups which have at least one role path `status` of `Ok` when supplying the `allowPartial` argument of `true` in the request.
 
 Devices MUST allow restoration of modified backups (full or partial backups where the data sets have been modified by a controller or provisioning tool) which have at least one role path `status` of `Ok` when supplying the `allowPartial` argument of `true` in the request.
 
-// TBD do we need to further define what a modified backup is?
+// TBD: Do we need to further define what a modified backup is?
 
 // TBD: Do we think some devices may need to be put in maintenance mode for restore to work?
 
-## 3. Restoring same unit but different version
+// TBD: Do we think some devices may need to reboot in order to apply a restore?
+
+## 3. Restoring same unit but different software version
 
-// TBD: Do we want to make this a MUST within the same Major version number?
+// TBD: Do we want to make this a MUST within the same Major software version number?
 
-## 4. Restoring different unit using the same version
+## 4. Restoring different unit using the same software version
 
 // TBD: Is this a MUST?
 
-// TBD: What if the new unit overwrites things like IP addresses? Are we saying the restore should be used as a bootstrap mechanism?
+// TBD: What if the new unit overwrites things like IP addresses? Are we saying the restore should be used as a bootstrap mechanism (do we need a isTemplate boolean flag when restoring)?