Skip to content

CloudEvents

This guide explains what CloudEvents are, why they are used in EventSourcingDB, and how the specification helps standardize event data across systems. Understanding the CloudEvents model will help you work more effectively with the structure and semantics of stored events.

What Are CloudEvents?

CloudEvents is an open specification defined by the Cloud Native Computing Foundation (CNCF) for describing events in a consistent and interoperable way. It defines a common structure for events, regardless of the system or service that produces them. The goal is to improve portability, observability, and integration across diverse platforms and tools.

EventSourcingDB uses CloudEvents as the foundation for how events are represented. Every event stored in EventSourcingDB follows the CloudEvents format, making it predictable, machine-readable, and easy to work with across languages and systems.

Standard Fields

EventSourcingDB supports all required and commonly used fields defined by the CloudEvents specification. These include:

  • specversion: Identifies the version of the CloudEvents specification. Automatically set by EventSourcingDB.
  • id: A unique identifier for the event. Automatically generated by EventSourcingDB.
  • time: The timestamp of when the event occurred. Automatically set by EventSourcingDB.
  • source: Describes the origin of the event – the system or component that produced it. See Sources.
  • subject: Represents the target or logical stream to which the event belongs. See Subjects.
  • type: Indicates the kind of event that occurred. See Event Types.
  • data: Contains the event payload, typically a domain-specific object in JSON format.
  • datacontenttype: Specifies the content type of the data field. Always set to application/json by EventSourcingDB.

These fields form the core structure of every event in EventSourcingDB. They are sufficient for describing most kinds of domain activity in a clear and standardized way. Their standardized structure supports both human readability and machine processing, which is essential for debugging, integration, and automation.

All fields not explicitly listed (e.g., extensions) are ignored.

OpenTelemetry Integration

EventSourcingDB also supports the optional fields traceparent and tracestate to facilitate integration with OpenTelemetry. These fields make it possible to correlate events with distributed traces and observe system behavior end to end.

Including tracing metadata is optional. If your application provides it, EventSourcingDB will store it alongside the event.

Event Format in Practice

While CloudEvents allows for flexibility in how events are serialized (e.g. binary vs. structured mode), EventSourcingDB standardizes on a structured JSON format. All event data is treated as JSON, and the content type is fixed to application/json.

This ensures consistency and simplifies parsing and tooling across environments.

Why It Matters

By adhering to the CloudEvents standard, EventSourcingDB makes it easier to:

  • Interoperate with external systems and tooling
  • Integrate with observability platforms
  • Build event-driven workflows and projections
  • Maintain consistency across distributed teams and services

CloudEvents is more than just a format – it provides a shared vocabulary and structure for describing what happened, where, and why. EventSourcingDB builds on this foundation to offer a reliable and standards-based event store.