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.

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

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/merge
path   /
status code  
  204 Success - the thing was merged successfully.
  403 Not Modifiable - Could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The attributes could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or attributes were not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The attribute could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or attribute was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The definition could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or definition was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  400 Policy ID invalid - The provided policyId is not valid.
  400 Not Deletable - The policyId of a thing cannot be deleted.
  403 Not Modifiable - The definition could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or definition was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The features could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or features were not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The feature could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or feature was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The definition could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing, feature or definition was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The properties could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The properties were not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The desired properties could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The desired properties were not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The property could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or property was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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.
  403 Not Modifiable - The desired property could not be merged as the requester had insufficient permissions (‘WRITE’ is required).
  404 Not Found - The thing or desired property was not found or requester had insufficient permissions.
    See Thing Error Responses for examples of other error responses.

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: protocol