Skip to content

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. 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-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 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 or observe APIs, but it is fully supported in EventQL.

  • 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.