In order to comply with the Ditto Protocol, a Protocol message must consist of

  • a Ditto Protocol envelope (JSON) and
  • a Ditto Protocol payload (JSON).

Ditto Protocol

The communication protocol envelope is implicitly defined by the underlying messaging system (e.g. WebSocket) used to transport/serialize the messages over the wire. Please refer to the respective communication protocol binding for information how to encode the data in a protocol specific way.

Ditto Protocol envelope

The Ditto Protocol envelope describes the content of the message (the affected thing entity, a message type, protocol version etc.) and allows the message to be routed by intermediary nodes to its final destination without parsing the actual payload.

The Protocol envelope is formatted as JSON object (content-type=application/json) and must correspond to the following JSON schema:

Ditto Protocol payload (JSON)

The Ditto model payload contains the application data, e.g. an updated sensor value or a Thing in JSON representation. See the specification for Things for the schema of a Thing.

Ditto Protocol response

When sending a command, a response can be requested. A response, can either indicate the success or the failure of the command. The Ditto response for a successful command has the following format:

In case the execution failed an error response with information about the error is sent:

The following sections specify in detail which fields of the Protocol envelope, payload and response are used to contain which information.


Protocol messages contain a topic which is used for

  • addressing an entity,
  • defining the channel (twin vs. live) and
  • specifying what the intention of the Protocol message is.


Protocol messages contain headers as JSON object with arbitrary content. There are some pre-defined headers which have a special meaning for Ditto:

Header Key Description Possible values
correlation-id Used for correlating Protocol messages (e.g. a command would have the same correlation-id as the sent back response message. String
version Determines in which schema version the sent along payload should be interpreted. Number - currently: [1,2]
response-required Configures for a sent command whether a response should be sent back. Boolean - default: true
If-Match Has the same semantics as defined for the HTTP API. String
If-None-Match Has the same semantics as defined for the HTTP API. String

Custom headers of messages through the live channel are delivered verbatim. When naming custom headers, it is best to attach a prefix specific to your application that does not conflict with Ditto or HTTP protocol, for example the prefix ditto-*.

  • Permanent HTTP headers are to be avoided.
  • Ditto uses the following headers internally. If these headers are set in a Protocol message, they will be ignored and will not be delivered.


Contains a JSON pointer of where to apply the value of the Protocol message. May also be / when the value contains a replacement for the complete addressed entity (e.g. a complete Thing JSON).


The JSON value to apply at the specified path.


Some Protocol messages (for example responses) contain a HTTP status code which is stored in this field.

Tags: protocol