# 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](mailto: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` *(Added in 1.2)* 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` *(Added in 1.1)* 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 *(Added in 1.1)* 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? - *(Added in 1.1)* 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? - *(Changed in 1.1)* 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**?