Things - Merge protocol specification • Eclipse Ditto™ • a digital twin framework

Edit this page

All topics contain the <channel> which may be either twin or live.
For the meaning of those two channels see Protocol specification.

For all merge commands the value field is provided in JSON merge patch format. In case of conflicts with the existing Thing, the value provided in the patch overwrites the existing value.

Merge a Thing

This command merges the Thing specified by the <namespace> and <thingName> in the topic with the JSON merge patch defined by the JSON in the value.

If the Thing did not yet exist, it is created.

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/`
value	The JSON value in JSON merge patch format that is applied to the Thing referenced in the `topic`.

Response

If the Thing was created successfully:

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/create`
path		`/`
value		The created Thing as JSON object, see Ditto protocol payload (JSON).
status	code
	`201`	Success - the Thing was created successfully.

If the Thing was merged successfully:

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/`
status	code
	`204`	Success - the Thing was merged successfully.

Event

The event emitted by Ditto after a Thing was merged.

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/`
value	The JSON merge patch that was applied to the Thing referenced in the `topic`.

Example: Merge a Thing

Merge all attributes of a Thing

Merge the attributes of a Thing identified by the <namespace> and <thingName> in the topic. The attributes will be merged with the JSON merge patch provided in the value field.

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/attributes`
value	The JSON value in JSON merge patch format that is applied to the attributes of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/attributes`
status	code
	`204`	Success - attributes were merged successfully.

Event

The event emitted by Ditto after the attributes of a Thing were merged.

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/attributes`
value	The JSON merge patch that was applied to the attributes of the Thing referenced in the `topic`.

Example: Merge attributes

Merge a single attribute of a Thing

Merge a specific attribute identified by the <attributePath> of the Thing. The attribute (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/attributes/<attributePath>`
value	The JSON value in JSON merge patch format that is applied to the attribute identified by `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/attributes/<attributePath>`
status	code
	`204`	Success - The attribute was merged successfully.

Event

The event emitted by Ditto after a single attribute was merged.

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/attributes/<attributePath>`
value	The JSON merge patch that was applied to the attribute identified by `path` of the Thing referenced in the `topic`.

Example: Merge a single attribute

Merge the definition of a Thing

Merge the definition of a Thing.

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/definition`
value	A valid Thing definition that replaces the definition of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/definition`
status	code
	`204`	Success - The definition was merged successfully.

Merge the policy ID of a Thing

Merge the policy ID of a Thing.

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/policyId`
value	A valid policy ID that replaces the policyId of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/definition`
status	code
	`204`	Success - The definition was merged successfully.

Event

The event emitted by Ditto after the definition was merged.

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/definition`
value	The JSON merge patch that was applied to the definition of the Thing referenced in the `topic`.

Example: Merge a definition

Merge all features of a Thing

Merge the features of a Thing identified by the <namespace> and the <thingName> in the topic.
The list of features will be merged with the JSON merge patch provided in the value.

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features`
value	The JSON value in JSON merge patch format that is applied to the features of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features`
status	code
	`204`	Success - The features were modified successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features`
value	The JSON merge patch that was applied to the features of the Thing referenced in the `topic`.

Example: Merge features

Merge a single feature of a Thing

Merge a specific feature (identified by the feature ID in the path) of the Thing (identified by the <namespace> and the <thingName> in the topic).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features/<featureId>`
value	The JSON value in JSON merge patch format that is applied to the specific feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features/<featureId>`
status	code
	`201`	Success - The feature was created successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features/<featureId>`
value	The JSON merge patch that was applied to the specific feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Example: Merge a single feature

Merge the definition of a feature

Merge the definition of a feature (identified by the feature ID in the path) of the Thing (identified by the <namespace> and the <thingName> in the topic).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features/<featureId>/definition`
value	The JSON value in JSON merge patch format that is applied to the definition of the feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features/<featureId>/definition`
status	code
	`204`	Success - the definition was merged successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features/<featureId>/definition`
value	The JSON merge patch that was applied to the definition of the feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Example: Merge feature definition

Merge all properties of a feature

Merge the properties of a feature (identified by the feature ID in the path) of the Thing (identified by the <namespace> and the <thingName> in the topic).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features/<featureId>/properties`
value	The JSON value in JSON merge patch format that is applied to the properties of the feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features/<featureId>/properties`
status	code
	`204`	Success - the properties were modified successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features/<featureId>/properties`
value	The JSON merge patch that was applied to the properties of the feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Example: Merge feature properties

Merge all desired properties of a feature

Merge the desired properties of a feature (identified by the feature ID in the path) of the Thing (identified by the <namespace> and the <thingName> in the topic).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features/<featureId>/desiredProperties`
value	The JSON value in JSON merge patch format that is applied to the desired properties of the feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features/<featureId>/desiredProperties`
status	code
	`204`	Success - the desired properties were modified successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features/<featureId>/desiredProperties`
value	The JSON merge patch that was applied to the desired properties of the feature identified by the feature ID in the `path` of the Thing referenced in the `topic`.

Example: Merge feature desired properties

Merge a single property of a feature

Merge a specific property (identified by <propertyPath>) of a feature (identified by the <featureId> in the path). The property (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features/<featureId>/properties/<propertyPath>`
value	The JSON value in JSON merge patch format that is applied to the property identified by the property path and the feature ID in `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features/<featureId>/properties/<propertyPath>`
status	code
	`204`	Success - the property was merged successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features/<featureId>/properties/<propertyPath>`
value	The JSON merge patch that was applied to the property identified by the property path and the feature ID in `path` of the Thing referenced in the `topic`.

Example: Merge a single feature property

Merge a single desired property of a feature

Merge a specific desired property (identified by <desiredPropertyPath>) of a feature (identified by the <featureId> in the path). The property (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).

Command

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/commands/merge`
path	`/features/<featureId>/desiredProperties/<desiredPropertyPath>`
value	The JSON value in JSON merge patch format that is applied to the desired property identified by the desired property path and the feature ID in `path` of the Thing referenced in the `topic`.

Response

Field		Value
topic		`<namespace>/<thingName>/things/<channel>/commands/merge`
path		`/features/<featureId>/desiredProperties/<desiredPropertyPath>`
status	code
	`204`	Success - the desired property was merged successfully.

Event

Field	Value
topic	`<namespace>/<thingName>/things/<channel>/events/merged`
path	`/features/<featureId>/desiredProperties/<desiredPropertyPath>`
value	The JSON merge patch that was applied to the property identified by the desired property path and the feature ID in `path` of the Thing referenced in the `topic`.

Example: Merge a single feature desired property

Tags: