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.

Ditto Protocol response

When sending a command, a response can be requested. A response can indicate either 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 use to contain which information.

Topic

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.

Headers

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
content-type The content-type of the message, for Ditto Protocol messages: application/vnd.eclipse.ditto+json String
correlation-id Used for correlating protocol messages (e.g. a command would have the same correlation-id as the sent back response message. String
ditto-originator Contains the first authorization subject of the command that caused the sending of this message. Set by Ditto. String
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
response-required Configures for a command whether or not a response should be sent back. Boolean - default: true
requested-acks Defines which acknowledgements are requested for a command processed by Ditto. JsonArray of String - default: ["twin-persisted"]
timeout Defines how long the Ditto server should wait, e.g. applied when waiting for requested acknowledgements. String - e.g.: 42s or 250ms or 1m - default: 60s
version Determines in which schema version the payload should be interpreted. Number - currently: [1,2]

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.
    channel
    ditto-*
    raw-request-url
    read-subjects
    subject
    timeout-access
    

The interaction between the headers response-required, requested-acks and timeout is documented here.

Path

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).

Value

The JSON value to apply at the specified path.

Status

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

Extra

When using signal enrichment, in order to ask for extraFields to be included, the Ditto Protocol message contains a field extra containing a JSON object with the selected extra fields.

Tags: protocol