schema_registry_converter

Releases

1. ▸▾5.0.025 Aug 2026Breaking2 sources agree

   Two breaking changes bump this to a major version:

   Two breaking changes bump this to a major version:

   BytesResult (in schema_registry_common) now borrows the payload instead of owning it -- Invalid(Vec<u8>) / Valid(u32, Vec<u8>) are now Invalid(&'a [u8]) / Valid(u32, &'a [u8]), and get_bytes_result returns BytesResult<'_> borrowing from its input, instead of copying the whole payload into a fresh Vec on every call. This is on the hot path of every decode, for every format (Avro, JSON, protobuf), so it matters more the larger your messages are -- see #190 for measurements.

   This only affects code that calls get_bytes_result/matches on BytesResult directly. The built-in AvroDecoder, JsonDecoder, ProtoDecoder and ProtoRawDecoder (blocking and async) are not affected -- their decode/decode_with_schema/etc. signatures haven't changed, and existing code calling those is unaffected. If you do call get_bytes_result directly and need to keep the bytes beyond the immediate match (store them, return them, carry them across an .await), copy them out explicitly where you used to get an owned Vec for free:

   match get_bytes_result(bytes) {
       BytesResult::Valid(id, bytes) => {
           let owned: Vec<u8> = bytes.to_vec();
           // ... use `owned` instead of `bytes` wherever it needs to outlive this match
       }
       BytesResult::Invalid(bytes) => {
           let owned: Vec<u8> = bytes.to_vec();
           // ...
       }
       BytesResult::Null => {}
   }
   

   Second, apache-avro moved from ^0.21 to ^0.22, which turned Name::name/Name::namespace (apache_avro::schema::Name, returned in DecodeResult.name/DecodeResultWithSchema.name) from public fields into methods returning borrows (name() -> &str, namespace() -> Option<&str>) instead of owned Strings. If you access those on a Name obtained through this crate, it's not just adding parentheses -- .unwrap() on the Option<Name> now needs .as_ref() first, or the borrow from .name()/.namespace() outlives the temporary it came from:

   // before (apache-avro 0.21, schema_registry_converter <5.0.0)
   let name: String = decode_result.name.unwrap().name;
   let namespace: Option<String> = decode_result.name.unwrap().namespace;
   // after (apache-avro 0.22, schema_registry_converter >=5.0.0)
   let name: &str = decode_result.name.as_ref().unwrap().name();
   let namespace: Option<&str> = decode_result.name.as_ref().unwrap().namespace();
   

   Not breaking, but worth knowing about: Avro encode/decode now reuse a cached, already-resolved schema instead of re-resolving it from scratch on every single call -- internal, not observable in the API, but measurably faster, more so the more named types (records/enums/fixed) your schema has. See #190.

   Add support for plugging in a reqwest_middleware::Middleware (async only, behind the new middleware feature) via SrSettingsBuilder, for short-lived tokens that need periodic refreshing (e.g. GCP workload identity federation) without recreating SrSettings -- and losing its schema cache -- every time a token expires. See #144 and the "Authentication middleware / token refresh" section of the README.

   Fix the blocking protobuf decoder (ProtoDecoder) missing well-known/common-type imports (e.g. google/protobuf/timestamp.proto) when they're imported by a referenced schema rather than the top-level one -- the async decoder already handled this correctly. See #178.

   Fix the blocking JSON decoder (JsonDecoder) skipping a reference that comes after one already present in its (persistent, cross-call) scope, even when the later reference is a different schema in the same reference list -- it was short-circuiting on the first "already resolved" match instead of checking each reference independently. See #177.

   Fix a retriable error (e.g. a transient 503 from the registry) getting stuck in a decoder's or encoder's cache -- every subsequent call for that schema id/guid kept replaying the same stale failure instead of retrying, until remove_errors_from_cache() was called by hand -- and fix SRCError.cached being applied inconsistently between the blocking and async clients along the way. Retriable errors are no longer cached by either client. See #171 and #175.

   Fix a panic when decoding a 5-byte (or otherwise malformed/truncated) protobuf-framed payload with ProtoDecoder/ProtoRawDecoder (blocking and async); such payloads now yield an SRCError instead. As part of this, proto_resolver::to_index_and_data is now fallible: it returns Result<(Vec<i32>, Vec<u8>), SRCError> instead of (Vec<i32>, Vec<u8>), a breaking change for any caller using that function directly. Fixes #176.

   Fix a follow-up issue in the same area: a brace character inside a string literal in a proto schema (e.g. a field/option default value) could desync MessageResolver/IndexResolver's index bookkeeping from the real message nesting, since its lexer didn't previously recognize string literals and treated every {/} as message nesting. String literals are now skipped as a whole when scanning for braces.

   Fix the blocking client silently dropping properties/tags metadata when registering a schema or reference (post_schema, post_reference) or checking compatibility -- blocking::schema_registry::get_body never received the metadata support async_impl::schema_registry::get_body already had. Both clients now build the same metadata block. See #174.

   Add support for carrying the schema id/guid in a Kafka header instead of prefixing the payload, matching Confluent Schema Registry 8.0's HeaderSchemaIdSerializer/DualSchemaIdDeserializer. Every encoder/decoder (Avro, JSON, protobuf; blocking and async) gains _with_header_id variants, plain-data types SchemaIdHeader/KEY_SCHEMA_ID_HEADER/VALUE_SCHEMA_ID_HEADER are added to schema_registry_common, and schema lookup by guid (GET /schemas/guids/{guid}) is now supported alongside lookup by id. No existing function/method signature changes, so this is additive for all normal usage -- but RegisteredSchema, RawRegisteredSchema, AvroSchema, and JsonSchema all gain a new public guid field, which is a breaking change if you construct one of those via struct-literal syntax, or destructure one exhaustively without ... See #139 and the "Schema id in Kafka headers" section of the README.

   AvroEncoder::encode_struct/encode_struct_with_header_id (blocking and async) no longer go through an untyped intermediate apache_avro::types::Value plus a separate Value::resolve() pass to make it match the schema -- they now serialize directly against the (still cached) resolved schema via apache_avro's schema-aware serde serializer. For a schema with several fields sharing the same named type, .resolve() alone used to dominate encode time; benchmarked about 7x faster on a schema with 8 such fields, and about 2.7x faster even on a schema with none (benches/avro_bench.rs's avro_encode_struct_cached_named_refs/avro_encode_struct_cached). Not breaking for normal usage, but the exact wording of the SRCError returned for a value that doesn't match its schema has changed (e.g. "Failed to resolve" is now "Could not get Avro bytes", with a more specific cause) -- don't match on that text. See #117.

   Add avro_common::get_supplied_schema_for::<T>(), building a SuppliedSchema straight from a type implementing apache_avro's own AvroSchema trait (most commonly via #[derive(apache_avro::AvroSchema)]) instead of hand-writing/maintaining the schema as a separate JSON string. Combine it with any *WithSchema SubjectNameStrategy variant, which already registers the schema if the registry doesn't have it yet. Purely additive -- a thin wrapper around the existing avro_common::get_supplied_schema. See #111 and the "Deriving an Avro schema from a struct" section of the README.