Skip to main content

Schema validation

Client-side validation holds only while every writer runs it. One service that skips it, one bug, and malformed events sit in an immutable log forever. Celeriant checks on the server: register a schema and the leader rejects a non-conforming event with WriteSchemaValidationFailed (2022) before anything is appended.

What a schema is keyed to​

A schema is keyed by (org, aggregate type, event_type_major, event_type_minor). Every exact pair needs its own registration. An event whose key has no schema is written unvalidated. No fallback to another minor, no warning.

That is the trap. Register 1.0, start writing 1.1, and the 1.1 events go in unchecked until you register 1.1 too. Put registration in the deploy pipeline, ahead of the code that emits the new version.

Schemas apply to new writes only. Events already in the log are never re-checked.

Formats​

JSON Schema, Avro or Protobuf (a base64 FileDescriptorSet plus a message name). The server compiles the schema at registration, so a malformed body fails there with RegisterSchemaInvalid (2021). The body is capped at --max-schema-size-bytes (default 16384), base64 descriptor included. Exact strings and pass rules per format are in Schema formats.

Registration is write-once​

Registering a key that already has a schema returns RegisterSchemaAlreadyExists (2020). There is no update and no delete, and compaction keeps schema records forever. A wrong schema stays wrong; a changed shape gets a new (major, minor).

Registration is a leader operation, fsynced and replicated like a write. It lands on shard 0, which then fans it out so every shard holds its own copy. If any shard fails you get RegisterSchemaCoordinationFailed (2029). Shard 0 keeps it, so a plain retry gets 2020 and does not re-send to the shards that missed.

Encrypted events skip validation​

An event carrying an iv is treated as ciphertext and skipped by the validator. It is written regardless of any schema for its type. Validate or encrypt, per type, not both.

See Registering and evolving schemas for client code.