Registering Event Schemas¶

This guide shows how to register JSON schemas for events in EventSourcingDB using its HTTP API. You'll learn how to associate a schema with an event type and how schema validation is enforced.

Registering a Schema¶

To validate incoming event data, you can register a JSON schema for a given event type. Each event type can have exactly one schema, and the schema applies to all events of that type – past and future.

To register a schema, send an HTTP request using POST to the /api/v1/register-event-schema endpoint:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer <API_TOKEN>" \
  -H "content-type: application/json" \
  -d "{
    \"eventType\": \"io.eventsourcingdb.library.book-acquired\",
    \"schema\": \"{
      \"type\": \"object\",
      \"properties\": {
        \"title\": { \"type\": \"string\" },
        \"author\": {\"type\": \"string\"},
        \"isbn\": {\"type\": \"string\"}
      },
      \"required\": [
        \"title\",
        \"author\",
        \"isbn\"
      ],
      \"additionalProperties\": false
    }\"
  }" \
  http://localhost:3000/api/v1/register-event-schema

If Something Goes Wrong

If you receive an error stating that the event type already has a schema, keep in mind that a schema cannot be modified or removed once registered. You must define a new event type if you need a different schema.

If everything worked as expected, the server will reply with HTTP status code 200 OK and the following response:

{
  "specversion": "1.0",
  "id": "0",
  "time": "...",
  "source": "https://www.eventsourcingdb.io",
  "subject": "/api/v1/register-event-schema",
  "type": "io.eventsourcingdb.api.event-schema-registered",
  "datacontenttype": "application/json",
  "data": {
    "eventType": "io.eventsourcingdb.library.book-acquired",
    "schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "author": {"type": "string"},
        "isbn": {"type": "string"}
      },
      "required": [
        "title",
        "author",
        "isbn"
      ],
      "additionalProperties": false
    }
  }
}

Schema Enforcement¶

Once a schema is registered for an event type:

All future events of that type must conform to the schema.
All existing events of that type are validated retroactively.
If any existing event violates the schema, the schema cannot be registered.

This guarantees that all events of a given type – past and future – are schema-compliant.

Because of this strict enforcement, schemas cannot be edited or deleted after registration. If you need to change a schema, you must define a new event type. It is therefore strongly recommended to include a version number in your event types, such as:

io.eventsourcingdb.library.book-acquired.v1
io.eventsourcingdb.library.book-acquired.v2

Why Versioning Matters

If you register a schema for an event type and later need to add a required field, you can't update the existing schema. Instead, you must define a new event type (e.g. with .v2) and update your producers and consumers accordingly.

Enforcing Known Event Types¶

By default, you can write events of any type, whether or not it has a registered schema – schemas are validated only where they exist. If you want to enforce a closed set of known event types, start the server with the --require-event-schemas flag:

./eventsourcingdb run [...] --require-event-schemas

With this enabled, the database rejects any write whose event type has no registered schema, so every event type must be registered before it can be written. This is an advanced, opt-in setting and is off by default, because turning it on rejects every type you have not registered a schema for yet.

Enforcement applies only to new writes: existing events are never touched, and enabling the flag does not retroactively validate the store. An event type that already exists but has no schema simply becomes unwritable until you register a schema for it.

To help you spot those, the server logs a warning at startup listing the existing event types that have no registered schema, so you know which ones still need one.

Enforcement also applies when restoring a backup: with the flag enabled, a backup may only be restored if every event type in it has a schema, otherwise the restore is rejected.

Your Turn¶

Try registering a schema for one of your existing event types – for example:

io.eventsourcingdb.library.book-acquired
io.eventsourcingdb.library.book-borrowed

Then try the following:

Try to write an event that matches the schema – it should be accepted.
Try to write an event that violates the schema – it should be rejected.

You can also try to register a schema after writing a few events. If those events are valid, the schema will be accepted. Otherwise, you'll get a validation error and the schema will not be stored.