# Sources

This guide explains the role of the **`source` field** in EventSourcingDB, how it is used, and what conventions are recommended. Though defined by the CloudEvents specification, the field also improves **traceability across systems**.

## What Is a Source?

The **`source` field is a required part of every event** in EventSourcingDB, as defined by the **[CloudEvents specification](https://github.com/cloudevents/spec)**. It identifies the **origin of the event** – the system, service, or application that produced it.

In EventSourcingDB, the `source` value is treated purely as **technical metadata**. It **does not affect event processing, stream assignment, or internal behavior**. However, it can be **useful when working across systems or tracing** where specific events came from.

## Format Requirements

*(Changed in 1.3)* The `source` must be a **URI that starts with a scheme**, such as `https:` or `tag:`. This is stricter than the CloudEvents standard, which also allows a relative reference such as `/library`; EventSourcingDB rejects such a value. **EventSourcingDB enforces this rule** but does not impose any further semantics or structure. Valid examples include:

- A **URL** representing the emitting system:
  ```
  https://library.eventsourcingdb.io
  ```

- A **[RFC 4151](https://datatracker.ietf.org/doc/html/rfc4151)**-compliant **tag URI**:
  ```
  tag:eventsourcingdb.io,2025:library
  ```

Both forms are supported. The choice depends on your needs:

- Use **URLs** if you want a human-readable reference and the emitting system has a stable public identity.
- Use **tag URIs** if you prefer a self-contained identifier that remains valid even if URLs change in the future.

*(Removed in 1.3; Broken in 1.2, fixed in 1.3)* EventSourcingDB stores the `source` **as it parses it**, which is not always as it was sent, and computes the hash of the event over the stored value. The scheme is written in lowercase, an empty fragment is dropped, and in the path of a URL, a space or a character such as `ä` is percent-encoded: `HTTPS://library.eventsourcingdb.io/a book#` is stored as `https://library.eventsourcingdb.io/a%20book`. To get back exactly what you sent, send a `source` that is already in this form.

**Avoid opaque values** such as UUIDs without context or placeholder strings – even if technically valid. While EventSourcingDB doesn't depend on the content of `source`, **meaningful identifiers improve clarity and traceability** for consumers and operators.

## Source and Event Identity

In the CloudEvents model, the **combination of `source` and `id` must be globally unique**. **EventSourcingDB guarantees uniqueness through the `id` field alone**, regardless of `source`. This simplifies integration and avoids coordination between sources.

However, if you plan to interoperate with external systems that rely on the CloudEvents identity model, it's still **good practice to ensure uniqueness across `source` and `id`**.

## Filtering by Source

While the `source` field has no impact on how events are written, read, or stored in EventSourcingDB, it **can be used as a filter criterion in [EventQL](/docs/eventsourcingdb/v1.2/eventql)** queries. This allows you to select events from specific origins when building projections or exporting data.

**Filtering by `source` is not supported in the standard [read](/learn/tutorials/first-steps-with-eventsourcingdb/reading-events) or [observe](/learn/tutorials/first-steps-with-eventsourcingdb/observing-events) APIs**, but it is fully supported in EventQL.

## Recommended Practices

- **Always provide a meaningful `source`** value that reflects the emitting system.
- **Prefer stable, long-term identifiers** over URLs that may change.
- **Use the tag URI format** (`tag:...`) for maximum portability and independence from infrastructure.
- **Keep the format consistent** across your system landscape to support filtering and debugging.

## Designing Sources Intentionally

Although EventSourcingDB does not rely on `source` for its core behavior, the field plays an **important role in system transparency** – especially in **multi-system or federated architectures**. A **consistent and well-structured approach to `source`** makes it easier to understand, trace, and filter events over time.

Don't just treat `source` as a spec requirement – use it as an opportunity to **improve observability and interoperability** across your system landscape.