# 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](/concepts/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](https://cloudevents.io/)** 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](/docs/eventsourcingdb/sources)**.
- **`subject`**: Represents the target or logical stream to which the event belongs. See **[Subjects](/docs/eventsourcingdb/subjects)**.
- **`type`**: Indicates the kind of event that occurred. See **[Event Types](/docs/eventsourcingdb/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](/learn/tutorials/first-steps-with-eventsourcingdb/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.1)* 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](/docs/eventsourcingdb/auditing-the-event-store)**.
- *(Added in 1.1)* **`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](/docs/eventsourcingdb/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](https://opentelemetry.io/)**. 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.