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.

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.