Skip to content

Compliance Criteria

This guide outlines the functional criteria that a client SDK must fulfill to be considered compliant with EventSourcingDB. It is intended for both internal use during SDK reviews and for external developers who wish to implement their own SDK for EventSourcingDB.

Client SDKs are expected to focus on application-level use cases such as writing, reading, and observing events. Operational and administrative features such as backup, restore, or health checks may be out of scope, depending on the SDK's intended usage.

Scope and Purpose

The criteria described here are used to assess SDK capabilities in a consistent and transparent way. They reflect the expectations for feature support based on the core HTTP API of EventSourcingDB.

Compliance is evaluated per SDK version and EventSourcingDB version. Partial support for certain categories is acceptable if documented accordingly.

This checklist focuses on externally observable behavior. It deliberately avoids transport-level details such as HTTP status codes, request headers, or low-level error formats. SDKs are expected to expose clear and meaningful outcomes, regardless of how these are implemented internally.

Criteria Overview

SDKs are evaluated across the following capability categories:

  • Essentials
  • Writing Events
  • Reading Events
  • Using EventQL
  • Observing Events
  • Metadata and Discovery
  • Testcontainers Support

Each category consists of specific capabilities. The presence of a green check mark (✓) in an SDK page indicates that the corresponding feature is supported and has been verified.

A check mark is only assigned if all related questions for that capability can be answered with "yes". These questions are formulated from the perspective of SDK users and reflect observable behavior rather than internal implementation details.

Review and Validation

Each official SDK is reviewed and tested by the EventSourcingDB team. Community SDKs are assessed based on the information available in their public repositories, and – if applicable – based on automated test suites and documentation.

The checkmarks shown on individual SDK pages reflect the latest known state and may change as SDKs evolve.

Versioning and Updates

Compliance criteria are version-specific. SDKs must indicate which version of EventSourcingDB they are compatible with, and all evaluations are tied to that specific version.

As EventSourcingDB evolves, new features may be added to the criteria. SDKs are not required to support newly added features retroactively but are encouraged to implement them as appropriate.

Contributing and Contact

If you are developing a new SDK and would like it to be reviewed or listed, or if you have suggestions for improving this checklist, please contact us at hello@thenativeweb.io.

We are happy to support trusted third parties in building high-quality SDKs for the EventSourcingDB ecosystem.

Detailed Requirements

The following sections define the individual capabilities required for each category in detail.

Each section outlines the expected behavior for a specific feature. All questions are phrased from the SDK user's perspective.

Essentials

Initialize the Client

This capability ensures that the SDK allows users to configure and instantiate a client instance that is ready to interact with EventSourcingDB.

  • Does the SDK support configuration for HTTP connections?
  • Does the SDK support configuration for HTTPS connections?
  • Does the SDK allow specifying an API token?
  • Does the SDK create the client instance without triggering any network requests?

Choose the API

This capability ensures that the SDK talks to each server through the API that the server offers, so that the same code runs against every supported version of EventSourcingDB.

  • Does the SDK find out on the first request of a client instance whether the server offers the v2 API, with a request to /api/v2/system/ping, and remember the answer for that instance?
  • Does the SDK use the v2 API whenever the server offers it?
  • If the server does not offer the v2 API, does the SDK either use the v1 API for every request, or signal an IncompatibleServer error?
  • Does the message of an IncompatibleServer error describe the mismatch without naming a version?

Ping the Server

This capability ensures that the SDK allows users to check whether EventSourcingDB is reachable.

  • Does the SDK provide a function that performs a request to /api/v2/system/ping?
  • Does the function verify whether an HTTP status code 200 OK is returned?
  • Does the function verify whether an event of type io.eventsourcingdb.api.ping-received is returned?
  • Does the function complete silently if the server is reachable?
  • Does the function signal an error if the server is not reachable?

Verify API Token

This capability ensures that the SDK allows users to check whether an API token is valid.

  • Does the SDK provide a function that performs a request to /api/v2/system/verify-token?
  • Does the function verify whether an HTTP status code 200 OK is returned?
  • Does the function verify whether an event of type io.eventsourcingdb.api.token-verified is returned?
  • Does the function complete silently if the API token is valid?
  • Does the function signal an error if the API token is not valid?

Detect a Stalled Connection

This capability ensures that no request waits forever for a server that has stopped answering, while a request that takes long but keeps answering is left to finish.

  • Does the SDK signal a ConnectionStalled error once nothing has arrived from the server for a set time, measured from sending the request until its end, including the wait before the response begins?
  • Does a heartbeat count as something that arrived, so that a long-running stream or write that sends heartbeats is never cut off?
  • Does this apply to every request, those with a single answer as well as streams?
  • Is the time 30 seconds by default, and can it be changed with a setting named stallTimeout, in the form usual for the language of the SDK, such as WithStallTimeout in Go or stall_timeout in Python?

Abort a Request

This capability ensures that a caller can end a single request early, for example because the request that it serves has ended.

  • Can a caller abort each request on its own, with the means usual for the language of the SDK, such as a context.Context in Go, a CancellationToken in .NET, or an AbortSignal in JavaScript, wherever the language has such a means?
  • Does aborting a stream end it?
  • Does aborting a write after it was sent signal an OutcomeUnknown error?

Handle Errors

This capability ensures that the SDK reports every failure in a way that a caller can act on, with the same names in every official SDK.

  • Does the SDK signal every error that the server reports with one error type named DbApiError, in the form usual for the language of the SDK, such as DBAPIError in Go or DbApiException in .NET?
  • Does that error expose the code exactly as the server sends it, together with the description, the details, and the HTTP status?
  • Does the SDK provide constants for the known codes, so that a caller can tell, for example, a precondition that does not hold (precondition-violated) from other failures without comparing strings?
  • When the SDK uses the v1 API, does it assign the codes of the v2 API to those failures of the v1 API that clearly match one?
  • Does the SDK signal an error if a stream that the server ends with an end item breaks off before that item?

Writing Events

Write Single Event

This capability ensures that the SDK supports writing a single event to EventSourcingDB.

  • Does the SDK provide a function that performs a request to /api/v2/data/write-events?
  • Does the function support sending exactly one event in the request?
  • Does the function return the event as stored by the server, including all server-assigned metadata?

Write Multiple Events

This capability ensures that the SDK supports writing multiple events to EventSourcingDB.

  • Does the SDK provide a function that performs a request to /api/v2/data/write-events?
  • Does the function support sending more than one event in a single request?
  • Does the function return the events as stored by the server, including all server-assigned metadata?
  • Does the function preserve the order of the events when sending them to the server?

Use isSubjectPristine

This capability ensures that the SDK supports writing events with the isSubjectPristine precondition.

  • Does the SDK support adding an isSubjectPristine precondition when writing a single event?
  • Does the SDK support adding an isSubjectPristine precondition when writing multiple events?
  • Does the SDK allow specifying the subject to which the precondition applies?
  • Does the SDK signal an error if the precondition is not met?

Use isSubjectPopulated

This capability ensures that the SDK supports writing events with the isSubjectPopulated precondition.

  • Does the SDK support adding an isSubjectPopulated precondition when writing a single event?
  • Does the SDK support adding an isSubjectPopulated precondition when writing multiple events?
  • Does the SDK allow specifying the subject to which the precondition applies?
  • Does the SDK signal an error if the precondition is not met?

Use isSubjectOnEventId

This capability ensures that the SDK supports writing events with the isSubjectOnEventId precondition.

  • Does the SDK support adding an isSubjectOnEventId precondition when writing a single event?
  • Does the SDK support adding an isSubjectOnEventId precondition when writing multiple events?
  • Does the SDK allow specifying both the subject and the expected event ID?
  • Does the SDK signal an error if the precondition is not met?

Use isEventQlQueryTrue

This capability ensures that the SDK supports writing events with the isEventQlQueryTrue precondition.

  • Does the SDK support adding an isEventQlQueryTrue precondition when writing a single event?
  • Does the SDK support adding an isEventQlQueryTrue precondition when writing multiple events?
  • Does the SDK allow specifying an EventQL query string which enforces the precondition?
  • Does the SDK signal an error if the precondition is not met?

Include OpenTelemetry Trace Context

This capability ensures that the SDK supports including distributed tracing context in events.

  • Does the SDK support including a traceparent field in an event?
  • Does the SDK support including a tracestate field if traceparent is also set?
  • Does the SDK include the trace context fields unmodified in the request?

Know Whether a Write Was Stored

This capability ensures that a caller can tell whether it is safe to repeat a write that failed. EventSourcingDB never stops a write halfway, so a write whose answer is lost may have been stored nonetheless.

  • When writing events or registering an event schema fails, does the SDK signal an OutcomeUnknown error, which includes the cause, whenever the write may have been stored nonetheless – for example after a ConnectionStalled error, a broken connection, an abort after sending, or a stream that ended without its end item?
  • Does the SDK report a write as certainly not stored only if the connection could not be established at all, or if the server refused the write before storing anything?
  • Does the SDK apply the same rule in every official SDK, regardless of what its language could tell about whether a request left completely?

Reading Events

Read Events by Subject

This capability ensures that the SDK supports reading all events for a given subject.

  • Does the SDK provide a function that performs a request to /api/v2/data/read-events?
  • Does the function support specifying a subject to read events for?
  • Does the function return all events for the given subject?
  • Does the function support processing events incrementally as they arrive?

Read Recursively

This capability ensures that the SDK supports reading events both non-recursively and recursively.

  • Does the SDK support setting the recursive option when reading events?
  • Does the SDK support reading events for a parent subject and all its sub-subjects?

Read Chronological and Anti-Chronological

This capability ensures that the SDK supports reading events both in chronological and anti-chronological order.

  • Does the SDK support setting the order option to control the read direction?
  • Does the SDK support both chronological and antichronological values?

Use Boundaries

This capability ensures that the SDK supports setting boundaries when reading events.

  • Does the SDK support setting lowerBound and upperBound to restrict the event range?
  • Does the SDK support inclusive and exclusive boundary types for the lower bound?
  • Does the SDK support inclusive and exclusive boundary types for the upper bound?

Use fromLatestEvent

This capability ensures that the SDK supports reading from the latest occurrence of a given event type.

  • Does the SDK support using fromLatestEvent to begin reading from the latest event of a given type?
  • Does the SDK allow specifying how to proceed if no matching event is found?

Using EventQL

Execute EventQL Queries

This capability ensures that the SDK supports querying events using EventQL.

  • Does the SDK provide a function that performs a request to /api/v2/data/run-eventql-query?
  • Does the function allow passing an EventQL query string?
  • Does the function expose the result rows to the caller?
  • Does the function support processing result rows incrementally as they arrive?

Observing Events

Observe Events by Subject

This capability ensures that the SDK supports observing events for a given subject.

  • Does the SDK provide a function that performs a request to /api/v2/data/observe-events?
  • Does the function allow specifying the subject to observe?
  • Does the function expose both historical and live events to the caller?
  • Does the function support processing events incrementally as they arrive?

Observe Recursively

This capability ensures that the SDK supports observing events both non-recursively and recursively.

  • Does the SDK support setting the recursive option when observing events?
  • Does the SDK support observing events for a parent subject and all its sub-subjects?

Use Boundaries

This capability ensures that the SDK supports setting boundaries when observing events.

  • Does the SDK support setting lowerBound to resume observation after a specific event?
  • Does the SDK support both inclusive and exclusive boundary types for the lower bound?

Use fromLatestEvent

This capability ensures that the SDK supports observing from the latest occurrence of a given event type.

  • Does the SDK support using fromLatestEvent to begin observing from the latest event of a given type?
  • Does the SDK allow specifying how to proceed if no matching event is found?

Metadata and Discovery

Register Event Schemas

This capability ensures that the SDK supports registering event schemas for event types.

  • Does the SDK provide a function that performs a request to /api/v2/data/register-event-schema?
  • Does the function support registering a JSON schema for a given event type?
  • Does the function allow specifying both the event type and the schema definition?
  • Does the function expose whether the schema registration was successful or rejected?

List Subjects

This capability ensures that the SDK supports listing existing subjects.

  • Does the SDK provide a function that performs a request to /api/v2/data/read-subjects?
  • Does the function allow specifying the subject to list?
  • Does the function require the caller to set the recursive option, which decides whether the subject alone or the subject with all its sub-subjects is listed?
  • Does the function support using / recursively to list all subjects?
  • Does the function support processing subjects incrementally as they arrive?

List Event Types

This capability ensures that the SDK supports listing all known event types.

  • Does the SDK provide a function that performs a request to /api/v2/data/read-event-types?
  • Does the function expose all known event types returned by the server?
  • Does the function expose whether an event type has events, as hasEvents?
  • Does the function expose any available schema that is included in the response?
  • Does the function support processing event types incrementally as they arrive?

List a Specific Event Type

This capability ensures that the SDK supports listing a specific event type.

  • Does the SDK provide a function that performs a request to /api/v2/data/read-event-type?
  • Does the function expose the event types returned by the server?
  • Does the function expose whether the event type has events, as hasEvents?
  • Does the function expose an available schema that is included in the response?
  • Does the function signal an error if the event type does not exist?

Verify Events

This capability ensures that the SDK supports verifying the integrity and authenticity of individual events on the client side.

  • Does the SDK provide a function to verify the hash of an event by recalculating it according to its version – version 1 without a prefix, version 2 with the prefix esdb:hash:v2: – over the data field exactly as received, and comparing it to the hash field?
  • Does the hash verification function fail with a HashVerificationFailed error if the hash is invalid, and with an UnsupportedHashVersion error that names the version if the hash is of a version the SDK does not support?
  • Does the SDK provide a function to verify the signature of an event by:
  • First verifying the hash,
  • Then validating the signature using a configured public key?
  • Does the signature verification function fail with an error if no public key is configured, the hash is invalid, or the signature is invalid?
  • Does the signature verification function fail with a SignatureVerificationFailed error if the signature is invalid?
  • Do both functions expose clear and deterministic results for their respective verification outcomes?

Testcontainers Support

Start and Stop EventSourcingDB in Tests

This capability ensures that the SDK supports managing a containerized instance of EventSourcingDB for integration tests using Testcontainers.

  • Does the SDK provide a function to start a containerized EventSourcingDB instance?
  • Does the function wait for the database to be ready before returning control to the test?
  • Does the SDK support stopping and cleaning up the container after tests?

Use Custom Configuration

This capability ensures that the SDK allows configuring the container with custom parameters.

  • Does the SDK allow specifying a custom API token for the container?
  • Does the SDK allow configuring the exposed port?
  • Does the SDK allow using signing keys?