Skip to content

Event Schemas

An event schema is a JSON Schema that describes the structure of an event type. EventSourcingKit can register your schemas with EventSourcingDB and require that every event type has one, which lets the database reject malformed events before they enter the store.

Associating a Schema with an Event

Schemas are discovered by file-name convention, not registered in code. You add a JSON Schema file named after your event's C# class, with the suffix .schema.json, and embed it in your assembly. For an event class BookRegistered, the file is BookRegistered.schema.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bookId": { "type": "string", "format": "uuid" },
    "title": { "type": "string" },
    "author": { "type": "string" }
  },
  "required": ["bookId", "title", "author"]
}

Mark the file as an embedded resource in your project file so EventSourcingKit can find it:

<ItemGroup>
  <EmbeddedResource Include="Events/BookRegistered.schema.json" />
</ItemGroup>

During discovery, EventSourcingKit matches each embedded *.schema.json resource to the event class of the same name and attaches the schema to that event type.

Requiring and Registering Schemas

Two options control what happens with schemas at startup:

  • RequireSchemasForAllEvents – when enabled, EventSourcingKit throws at startup if any discovered event type is missing a schema. Use it to guarantee that every event you write is described.
  • AutoRegisterEventSchemas – when enabled, EventSourcingKit registers each discovered schema that the store does not yet know about, so your schemas are published automatically as you deploy.

Where validation happens

EventSourcingKit discovers and registers schemas; it does not validate event payloads itself. Enforcing a payload against its registered schema is EventSourcingDB's responsibility. EventSourcingKit's own check is the startup presence check gated by RequireSchemasForAllEvents.

For More Information