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.
Create a schema
Section titled “Create a schema”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.
Add a version
Section titled “Add a version”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.
Check without registering
Section titled “Check without registering”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.
Read schemas
Section titled “Read schemas”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.
List schemas
Section titled “List schemas”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.
Delete a schema
Section titled “Delete a schema”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.
Exceptions
Section titled “Exceptions”| 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 |