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. Partner and 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?

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/v1/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/v1/verify-api-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.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?

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/v1/write-events?
  • Does the function support sending exactly one event in the request?
  • Does the function verify whether an HTTP status code 200 OK is returned?
  • 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/v1/write-events?
  • Does the function support sending more than one event in a single request?
  • Does the function verify whether an HTTP status code 200 OK is returned?
  • 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?

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/v1/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/v1/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/v1/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/v1/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/v1/read-subjects?
  • Does the function support using / as the base subject to list all subjects?
  • Does the function allow specifying a custom baseSubject to limit the scope of the response?
  • 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/v1/read-event-types?
  • Does the function expose all known event types returned by the server?
  • Does the function expose whether an event type is marked as phantom?
  • 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/v1/read-event-type?
  • Does the function expose the event types returned by the server?
  • Does the function expose whether the event type is marked as phantom?
  • 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 and comparing it to the hash field?
  • Does the hash verification function fail with an error if the hash is invalid?
  • 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?
  • 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?