Enhance model and APIs with "desiredProperties" for Features

[thjaeckle]

Actual issue for implementing the model discussed first in #125 and now being part of #696

The latest proposal is the following JSON structure containing the "desiredProperties" needed for #696:

{
  "thingId": "org.eclipse.ditto:my-thermostat-1",
  "policyId": "org.eclipse.ditto:my-thermostat-1",
  "features": {
    "Thermostat": {
      "definition": [ "org.eclipse.ditto:Thermostat:1.0.0" ],
      "properties": {
        "status": {
          "measured-temperature": 20
        },
        "configuration": {
          "target-temperature": 20.0
        }
      },
      "desiredProperties": {
        "configuration": {
          "target-temperature": 22.0
        }
      }
    }
  }
}

Explanation:

• aside to properties the new Ditto managed field desiredProperties is added
• the same definition applies for both properties and desiredProperties
  • however, inside desiredProperties all mandatory properties defined by the definition are optional
• once a desiredProperties property is set (e.g. by a backend application or mobile app), the actual device has the task to apply that and reflect the applied desiredProperties property in the same one below the properties object
• when desiredProperties is not existing or is empty, all desired property changes were applied, none are pending

The pros/cons of this approach (other formats were already discussed in #125) are:

+:

• same definition is shared for properties and desired
  • (future topic relevant for schema validation): however, for desired the "required" properties defined in the Vorto model probably have all to be optional
• defines fine grained which deltas should be sent downlink
• policy may be written in a way which defines different access rights for properties/desiredProperties
• search can use desiredProperties and/or reported properties (even in combination)
• reduced unneeded payload duplication (besides properties hierarchy structure in JSON)
• no need for a desired channel in addition to twin/live - that would be "just" another JsonPointer path in the twin

-:

• is currently NOT possible by convention before implementing the model enhancement

Interim format until model is implemented

In order to mitigate the negative point, that this format is not usable in the meantime until the Ditto model was enhanced, the following interim format is suggested:

Click to see the interim format

{
"thingId": "org.eclipse.ditto:my-thermostat-1",
"policyId": "org.eclipse.ditto:my-thermostat-1",
"features": {
  "Thermostat": {
    "definition": [ "org.eclipse.ditto:Thermostat:1.0.0" ],
    "properties": {
      "~properties": {
        "status": {
          "measured-temperature": 20
        },
        "configuration": {
          "target-temperature": 20.0
       }
      },
      "~desiredProperties": {
        "configuration": {
          "target-temperature": 22.0
        }
      }
    }
  }
}
}

All API calls would work very similar to the future structure. Partial GET/PUT semantics are similarly supported.

The character prefix "~" is used to mark that this is the preliminary convention and this allows a simpler migration towards the target format.

Migration is later possible by:

• rewriting all paths: "properties/~properties" → "properties" and "properties/~desiredProperties" → "desiredProperties"

A script could optionally migrate existing things/policies from the interim format to the actual one once implemented.