Skip to content

Registration

Registration decides whether Kurrent Surge puts your schemas into the registry, and validation decides whether it checks them before use. One options object carries both.

Preset Registration Validation Use when
Disabled manual off default. The registry is not in your path
AutoRegister automatic off development, and any service that owns its schemas
Strict manual on production consumers that must fail fast on drift
builder.Services.AddKurrentSurge(surge => surge
.Connection("kurrentdb://localhost:2113", opts =>
opts.Schema = KurrentClientSchemaOptions.AutoRegister));

Outside DI, set it the same way on KurrentClient.Create:

await using var client = KurrentClient.Create(
"kurrentdb://localhost:2113",
opts => opts.Schema = KurrentClientSchemaOptions.Strict);

Disabled touches the registry for nothing. Schema names still resolve through your catalog, so append and read work. The registry is not consulted at all.

AutoRegister walks your catalogs when the client initializes and registers every schema that is not there. A schema that already exists is left alone. Nothing is validated, because you are the one defining the schemas.

Strict registers nothing and requires every catalog schema to be present and compatible before the client will use it. An unregistered type, or one whose shape has drifted from the registered version, fails at initialization rather than at the first append.

RegistrationMode takes SchemaRegistrationMode.Manual or .Auto. ValidationMode takes SchemaValidationMode.Disabled or .Enabled. NameStrategy decides how a schema name is derived when the type does not pin one. AppendAsJson appends records that state no format as JSON instead of taking the format from the message type. The three presets are just combinations of the first two, and you can set every member individually.

Whatever the wire format, the definition sent to the registry is a JSON Schema exported from your CLR type. A Protobuf-encoded or Avro-encoded record registers the same kind of definition a JSON one does.

That is what lets compatibility modes work uniformly: one comparable shape per schema name, regardless of encoding. The exception is Bytes, which never reaches the registry at all. See Data Formats.

The catalog walk runs once, single-flight, on the client’s initialization path. Every caller shares the same task, faults included. A registration failure therefore surfaces on the first operation rather than being retried per record.