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 assigned by EventSourcingDB as a sequential, zero-based numeric string ("0", "1", "2", and so on).
  • time: The timestamp of when the event occurred. Automatically set by EventSourcingDB as an RFC 3339 timestamp with nanosecond precision in UTC.
  • 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 as a JSON object. The top level must be an object – null, arrays, and scalar values are rejected. An empty object {} is allowed, for example for events whose type alone carries the meaning.
  • 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.

When writing events, you provide only source, subject, type, and data – plus optionally traceparent and tracestate; everything else is set by EventSourcingDB. Events that contain any other field are rejected.

EventSourcingDB Extension Attributes

In addition to the standard fields, every event returned by EventSourcingDB carries three extension attributes:

  • hash: A SHA-256 hash of the event, represented as 64 hexadecimal characters.
  • predecessorhash: The hash of the event that was written immediately before this one – across the entire event store, not per subject. The very first event of the store has a predecessor hash of all zeros. Together, hash and predecessorhash form a verifiable chain over all events, which can be used to detect tampering. See Auditing the Event Store.
  • signature: An Ed25519 signature of the event. It is only set if the server is configured with a signing key, otherwise it is null. See Verifying Event Signatures.

These attributes are managed entirely by EventSourcingDB. You never provide them when writing events.

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.