Remembering
EventSourcingDB
Building
ArchitectureKit
Version
1.2 · latest1.11.0
Docs / EventSourcingDB 1.0 / Fundamentals / CloudEvents

CloudEvents

This guide explains how EventSourcingDB uses CloudEvents, which fields it sets, and which extension attributes it adds. Understanding this will help you work more effectively with the structure and semantics of stored events. For CloudEvents as a standard, see CloudEvents in Concepts.

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 uses all required fields of the CloudEvents specification and all optional ones except dataschema:

  • 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 was written to the store, not of when the described occurrence took place. Automatically set by EventSourcingDB as an RFC 3339 timestamp with nanosecond precision in UTC. If a point in time matters to your domain, put it into data, where you control its meaning.
  • 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.

The optional field dataschema, which identifies the schema that data adheres to, is not supported. To validate the data of events, register a JSON schema for their event type instead – see Registering Event Schemas.

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#

Changed in 1.1In addition to the standard fields, every event returned by EventSourcingDB carries two 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.

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.