add new wot-models definition update endpoint #1843

[hu-ahmed]

Resolves: #1843

The migrateThingDefinition endpoint introduces a comprehensive mechanism for migrating a Thing's definition while ensuring data consistency and applying necessary migrations. This endpoint is designed to facilitate seamless updates by incorporating a structured approach to definition changes and migration payloads.

Key Features:

• Definition Update with Skeleton Generation:
  The provided Thing definition URL is used to generate a new skeleton Thing, which serves as the baseline for the update.
  The skeleton includes a hierarchical representation of the Thing, ensuring consistency with the WoT model.

• Patch Condition Evaluation:
  The migration payload can include multiple patch conditions, evaluated using RQL-based expressions to determine whether specific updates should be applied.
  This allows for conditional updates based on existing Thing attributes or feature values.

• Merging Strategy:
  The update process merges the newly generated skeleton with the existing Thing while preserving essential attributes and properties.
  An optional initialization step applies default values from the skeleton to fill in missing or incomplete properties.

• Migration Payload Application:
  The provided migration payload is selectively merged into the updated Thing, allowing for targeted modifications without overriding all properties.
  Ensures data integrity by applying only necessary changes based on predefined rules.

• Dry-Run Mode:
  The API supports a dry-run option (dryRun: true), allowing users to simulate the migration without persisting changes.

• Validation and Persistence:
  Before finalizing the update, the modified Thing undergoes WoT model validation based on the current configuration, so either it will be rejected or logged as warning in case of inconsistency.

• Ditto Protocols supported:
  this command is also available for other ditto protocols

• API Usage:
  Endpoint:
  POST /api/2/things/{thingId}/migrateDefinition
  Request Body:

{
  "thingDefinitionUrl": "https://models.example.com/thing-definition-1.0.0.tm.jsonld",
  "migrationPayload": {
    "attributes": {
      "manufacturer": "New Corp",
      "location": "Berlin, main floor"
    },
    "features": {
      "thermostat": {
        "properties": {
          "status": {
            "temperature": {
              "value": 23.5,
              "unit": "DEGREE_CELSIUS"
            }
          }
        }
      }
    }
  },
  "patchConditions": {
    "thing:/features/thermostat": "not(exists(/features/thermostat))"
  },
  "initializeMissingPropertiesFromDefaults": true
}

[thjaeckle]

Hi @hu-ahmed and thanks a lot for providing this PR.

Looks already really promising .. I did a quick check and left a few comments before going deeper :)

[thjaeckle]

All review remarks were addressed.
Thanks for squashing into a single commit 👍

And thanks a lot for this great addition to the Ditto WoT integration @hu-ahmed