Things

Update the definition of an existing Thing

POST
https://ditto.eclipseprojects.io/api/2/things/{thingId}/migrateDefinition

Updates the definition of the specified thing by providing a new definition URL along with an optional migration payload.

The request body allows specifying:

  • A new Thing definition URL.
  • A migration payload containing updates to attributes and features.
  • Patch conditions to ensure consistent updates.
  • Whether properties should be initialized if missing.

Placeholders in migration payload: String values in migrationPayload may use the thing-json placeholder. Both brace {{ thing-json:<json-pointer> }} and legacy ${ thing-json:<json-pointer> } are supported.

If the dry-run query parameter or header is set to true, the request will return the calculated migration result without applying any changes.

Example:

{
  "thingDefinitionUrl": "https://example.com/new-thing-definition.json",
  "migrationPayload": {
    "attributes": {
      "manufacturer": "New Corp"
    },
    "features": {
      "sensor": {
        "properties": {
          "status": {
            "temperature": {
              "value": 25.0
            }
          }
        }
      }
    }
  },
  "patchConditions": {
    "thing:/features/sensor": "not(exists(/features/sensor))"
  },
  "initializeMissingPropertiesFromDefaults": true
}

Body

application/json

JSON payload containing the new definition URL, migration payload, patch conditions, and initialization flag.

JSON payload to migrate the definition of a Thing.

thingDefinitionUrlstring<uri>required

The URL of the new Thing definition to be applied.

Example
https://models.example.com/thing-definition-1.0.0.tm.jsonld
migrationPayloadobject

Optional migration payload with updates to attributes and features. String values may contain {{ thing-json: }} placeholders to reference existing Thing data (e.g. attributes/location, features/sensor/properties/temp). Resolved values keep their JSON type; missing paths cause the request to fail.

Show child attributes
attributesobject

Attributes to be updated in the thing.

Example
{
  "manufacturer": "New Corp",
  "location": "Berlin, main floor"
}
featuresobject

Features to be updated in the thing.

Show child attributes
[key: string]object
Show child attributes
propertiesobject
Example
{
  "thermostat": {
    "properties": {
      "status": {
        "temperature": {
          "value": 23.5,
          "unit": "DEGREE_CELSIUS"
        }
      }
    }
  }
}
patchConditionsobject

Optional conditions to apply the migration only if the existing thing matches the specified values.

Show child attributes
[key: string]string
Example
{
  "thing:/features/thermostat": "not(exists(/features/thermostat))"
}
initializeMissingPropertiesFromDefaultsbooleanfalse

Flag indicating whether missing properties should be initialized with default values.

Example
true

Parameters

thingIdstringrequiredpath

The ID of a thing needs to follow the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).

dry-runbooleanfalsequery

If set to true, performs a dry-run and returns the migration result without applying changes.

Response

200OKMigrateThingDefinitionResponse

The thing definition was successfully updated, and the updated Thing is returned.

Response fields application/json

Response payload after applying or simulating a migration to a Thing.

thingIdstringrequired

Unique identifier representing the migrated Thing.

patchobjectrequired

The patch containing updates to the Thing.

Show child attributes
definitionDefinition

A single fully qualified identifier of a definition in the form '::' or a valid HTTP(s) URL

attributesAttributes

An arbitrary JSON object describing the attributes of a thing.

featuresFeatures

List of features where the key represents the featureId of each feature. The featureId key must be unique in the list.

Show child attributes
[key: string]Feature
Show child attributes
definitionArray<string>

The definitions of a feature.

propertiesFeatureProperties

An arbitrary JSON object describing the properties of a feature.

desiredPropertiesFeatureDesiredProperties

An arbitrary JSON object describing the desired properties of a feature.

mergeStatusstringAPPLIEDDRY_RUNrequired

Indicates the result of the migration process.

  • APPLIED: The migration was successfully applied.
  • DRY_RUN: The migration result was calculated but not applied.
Example
APPLIED
202AcceptedMigrateThingDefinitionResponse

Dry-run successful. The migration result is returned without applying changes.

Response fields application/json

Response payload after applying or simulating a migration to a Thing.

thingIdstringrequired

Unique identifier representing the migrated Thing.

patchobjectrequired

The patch containing updates to the Thing.

Show child attributes
definitionDefinition

A single fully qualified identifier of a definition in the form '::' or a valid HTTP(s) URL

attributesAttributes

An arbitrary JSON object describing the attributes of a thing.

featuresFeatures

List of features where the key represents the featureId of each feature. The featureId key must be unique in the list.

Show child attributes
[key: string]Feature
Show child attributes
definitionArray<string>

The definitions of a feature.

propertiesFeatureProperties

An arbitrary JSON object describing the properties of a feature.

desiredPropertiesFeatureDesiredProperties

An arbitrary JSON object describing the desired properties of a feature.

mergeStatusstringAPPLIEDDRY_RUNrequired

Indicates the result of the migration process.

  • APPLIED: The migration was successfully applied.
  • DRY_RUN: The migration result was calculated but not applied.
Example
APPLIED
400Bad RequestAdvancedError

The request could not be processed due to invalid input.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

401UnauthorizedAdvancedError

Unauthorized request due to missing authentication.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

404Not FoundAdvancedError

The specified thing could not be found.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

412Precondition FailedAdvancedError

The update conditions were not met.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

Authorization

OpenIDConnectopenIdConnect

OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.

NginxBasichttp (basic)

Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)

Bearerhttp (bearer)

A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Docs by Sourcey
↑↓ navigate↵ selectesc close