Signals & Communication Pattern

Signals are the messages that flow through Ditto. Every interaction – creating a Thing, querying a property, receiving a change notification – is carried by a signal.

Overview

Ditto follows the CQRS and Event Sourcing architectural patterns. This page provides a good explanation of the basic concepts:

People request changes to the domain by sending commands. They are named with a verb in the imperative mood plus and may include the aggregate type, for example ConfirmOrder. Unlike an event, a command is not a statement of fact; it’s only a request, and thus may be refused.

An event represents something that took place in the domain. They are always named with a past-participle verb, such as OrderConfirmed. Since an event represents something in the past, it can be considered a statement of fact and used to take decisions in other parts of the system.

Every change goes through a well-defined flow:

1. A Command arrives requesting a change or a query.
2. Ditto processes it and sends back either a Command Response (success) or an Error Response (failure).
3. If the command modified data, Ditto persists an Event and publishes it to subscribers.

All signal types share common header fields (like correlation IDs) that let you trace a request through its entire lifecycle.

Commands

Commands are requests to change or retrieve data from a digital twin or a connected device. Every command targets a specific entity by its ID (for example, a Thing ID).

See Commands detail for the full command lifecycle.

Modify commands

Modify commands change the state of a digital twin or trigger an action on a device. In CQRS terminology, these are the “commands” (write side).

Related protocol specifications:

• Create/Modify protocol specification
• Merge protocol specification
• Delete protocol specification

Query commands

Query commands retrieve data without changing anything. In CQRS terminology, these are the “queries” (read side).

Related protocol specification:

• Retrieve protocol specification

Command Responses

A command response is the reply to a command. It tells you whether the operation succeeded:

• For modify commands: the response confirms the change was applied (for example, 201 Created or 204 No Content).
• For query commands: the response contains the requested data.

If something goes wrong, you receive an error response instead.

See Command Responses detail for response structure and examples.

Error Responses

When a command or message fails, Ditto sends an error response explaining what went wrong. Failures can happen for many reasons:

• Missing permissions
• Entity not found
• Invalid input data
• Internal server errors

The Ditto Protocol for Errors defines the error response format. See also Error Responses detail.

Example error responses:

• Things error responses
• Policies error responses

Events

Events record that something already happened. They are past tense and irreversible – the change is already persisted.

See Events detail for event structure and persistence.

Events serve three purposes in Ditto:

1. Persistence – appended to the event journal (event sourcing) as the source of truth
2. Internal coordination – published within the Ditto cluster so services can react (for example, the search index updates itself based on events)
3. External notification – delivered to authorized subscribers via the WebSocket API, HTTP Server Sent Events, and connection targets as change notifications

Announcements

Announcements signal that something is about to happen. Unlike events, announcements are forward-looking and are not persisted.

For example, before a Policy subject expires, Ditto can publish an announcement so your application can react – perhaps by renewing the subject’s credentials.

Announcements are published to authorized subscribers via the WebSocket API and connection targets.

See Announcements detail for announcement types and examples.

Communication pattern summary

Further reading

• Change Notifications – subscribe to events via different APIs
• Signal Enrichment – add extra context to events
• Messages – send arbitrary payloads to/from devices
• Ditto Protocol specification – wire format for all signal types