# 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

The `source` must be a **valid URI-reference**, as required by the CloudEvents standard. **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.

**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/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.