# CloudEvents

This guide explains what **CloudEvents** are, why they matter for event-sourced systems, 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.

## Standard Fields

The **[CloudEvents specification](https://cloudevents.io/)** describes every event with a small set of **context attributes**. Four of them are **required**:

- **`specversion`**: Identifies the version of the CloudEvents specification the event uses.
- **`id`**: Identifies the event. Together with `source`, it must be **unique for each distinct event**.
- **`source`**: Describes the origin of the event – the context in which it happened, such as the system or component that produced it.
- **`type`**: Indicates the kind of event that occurred.

Others are **optional**:

- **`subject`**: Identifies the subject of the event in the context of its producer – in event-sourced systems, typically the stream to which the event belongs.
- **`time`**: The timestamp of when the occurrence happened. If that cannot be determined, a producer may use another time, such as the current time, as long as it does so consistently.
- **`datacontenttype`**: Specifies the content type of the `data` field.
- **`dataschema`**: Identifies the schema that `data` adheres to.

The payload itself is carried in **`data`**.

**These fields form the core structure of every event.** 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.

## Extension Attributes

In addition to the standard fields, an event may carry any number of **extension attributes** that add further context. They follow the same naming conventions and type system as the standard fields.

One example is the **distributed tracing extension**: its fields **`traceparent`** and **`tracestate`** carry the context of **[W3C Trace Context](https://www.w3.org/TR/trace-context/)** and 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.

## Event Format in Practice

CloudEvents allows for flexibility in how events are serialized (e.g. binary vs. structured mode). Standardizing on a single format – for example, **structured JSON** – **ensures consistency and simplifies parsing and tooling** across environments.

## Why It Matters

By **adhering to the CloudEvents standard**, an event store 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.

> **Try it with EventSourcingDB**
>
> EventSourcingDB uses CloudEvents as the foundation for how events are represented – see **[CloudEvents](/docs/eventsourcingdb/cloud-events)** in its documentation for the fields it sets and the extension attributes it adds.