Protocol specification

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.

Content-type

Ditto Protocol messages are identified by the IANA registered “Content-Type”:

application/vnd.eclipse.ditto+json

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 specification for Things
• See specification for Policies
• See specification for Connections

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. The keys of the JSON object are the header names; the values are the header values.

The header names are case-insensitive and case-preserving in the following sense:

• Case-insensitive: Capitalization of header names does not affect evaluation of the headers by Ditto; setting correlation-id or CORRELATION-ID has the same effect. If 2 headers differing only in capitalization are set, Ditto’s behavior is not defined.
• Case-preserving: Capitalization of headers by the sender of a Ditto protocol message is visible to the receiver. An exception to case-preservation are the headers of HTTP requests and responses, since they are themselves not case-sensitive.

There are some pre-defined headers, which have a special meaning for Ditto:

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