Skip to content

Registry

client.Registry manages schema definitions and their versions. A schema has a name, a data format, a compatibility mode, and an ordered list of versions.

Most applications never call this module directly, because registration does it for you when you turn it on. Reach for it when you manage schemas out of band, or need to inspect what is registered.

Registers the schema and its first version in one call. Pick the compatibility mode here. The registry enforces it on every later version.

var descriptor = await client.Registry.CreateSchema(new CreateSchemaOptions {
SchemaName = "order-placed",
SchemaDefinition = schemaJson,
DataFormat = SchemaDataFormat.Json,
CompatibilityMode = CompatibilityMode.Backward,
Description = "Order placed event",
Tags = new Dictionary<string, string> { ["domain"] = "orders" }
});

Or the short form:

var descriptor = await client.Registry.CreateSchema(
"order-placed", schemaJson, SchemaDataFormat.Json, CompatibilityMode.Backward);

Returns SchemaVersionDescriptor: VersionId and VersionNumber.

VersionId is the durable handle. Hold it in code that binds to a specific contract. VersionNumber is sequential per schema and convenient for humans, but it is not an identifier.

Option Type Meaning
SchemaName SchemaName Unique per registry
SchemaDefinition string The definition itself
DataFormat SchemaDataFormat Json, Protobuf, Avro, or Bytes. Defaults to Unspecified, which the request rejects — set it
CompatibilityMode CompatibilityMode Defaults to None
Description string Free text
Tags IDictionary<string,string> For search and discovery

Throws SchemaAlreadyExistsException if the name is taken.

New versions inherit the schema’s data format. The server checks the definition against the schema’s compatibility mode and rejects anything outside it.

var v2 = await client.Registry.RegisterSchemaVersion("order-placed", updatedJson);

Throws SchemaIncompatibleException, whose Errors list every violation with a property path, or SchemaNotFoundException if the schema does not exist.

Same rules as registration, no change to the registry. Use it in CI, or before committing to a version.

SchemaVersionId matched = await client.Registry.CheckSchemaCompatibility(
SchemaName.From("order-placed"),
opts => {
opts.SchemaDefinition = proposedJson;
opts.DataFormat = SchemaDataFormat.Json;
});

Identifier accepts either a SchemaName, which checks against the latest version, or a SchemaVersionId, which checks against that specific one. The latter is what you want for a rollback dry-run.

GetSchema returns metadata only. GetSchemaVersion returns a version including its definition.

Schema schema = await client.Registry.GetSchema("order-placed");
SchemaVersion latest = await client.Registry.GetSchemaVersion("order-placed");
SchemaVersion v2 = await client.Registry.GetSchemaVersion("order-placed", versionNumber: 2);
SchemaVersion byId = await client.Registry.GetSchemaVersionById(descriptor.VersionId);

All throw SchemaNotFoundException for an unknown name or number, and SchemaDeletedException if the parent schema was deleted.

IReadOnlyList<Schema> all = await client.Registry.ListSchemas();
IReadOnlyList<Schema> orders = await client.Registry.ListSchemas(schemaNamePrefix: "order-");
IReadOnlyList<Schema> filtered = await client.Registry.ListSchemas(new ListSchemasOptions {
SchemaNamePrefix = "order-",
Tags = new Dictionary<string, string> { ["team"] = "fulfillment" }
});

Tag filters require every named tag to match. No filters returns everything.

Removes the schema and every version it holds.

Success ok = await client.Registry.DeleteSchema("order-placed");

Destructive. Consumers holding a SchemaVersionId from this schema start receiving SchemaDeletedException. Coordinate before deleting anything shared.

Exception Cause
SchemaAlreadyExistsException The name is already registered
SchemaNotFoundException No such schema, version number, or version id
SchemaDeletedException The schema was deleted
SchemaIncompatibleException The definition violates the compatibility mode. See Errors
ValidationException The request is missing required fields