This is an automated email from the ASF dual-hosted git repository.
AndrewJSchofield pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 205b70af944 KAFKA-12570: Document compact arrays in flexible versions
(#22862)
205b70af944 is described below
commit 205b70af944be4a9620f2df035f4b96469bdd506
Author: Gabriel Dutra <[email protected]>
AuthorDate: Mon Jul 27 01:53:25 2026 -0700
KAFKA-12570: Document compact arrays in flexible versions (#22862)
## What changed
- explain that flexible message versions use compact encodings for
variable-length fields
- explicitly document that arrays use `COMPACT_ARRAY` instead of `ARRAY`
- mention the related compact string and byte-array encodings,
variable-length length prefix, and tagged-fields section
## Why
The protocol primitive-type table lists compact encodings but did not
explain when clients must use them. This left implementers to infer that
flexible message versions use `COMPACT_ARRAY` and the other `COMPACT_*`
types.
## Impact
Client implementers can now determine the correct array encoding for
flexible message versions directly from the wire-protocol guide.
## Validation
- `./gradlew siteDocsTar`
- `git diff --check`
Reviewers: Andrew Schofield <[email protected]>
Co-authored-by: gabrieldutra <[email protected]>
---
docs/design/protocol.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/design/protocol.md b/docs/design/protocol.md
index 8f0b763abad..70169e1793b 100644
--- a/docs/design/protocol.md
+++ b/docs/design/protocol.md
@@ -138,6 +138,8 @@ The protocol is built out of the following primitive types.
{{< include-html file="/static/{version}/generated/protocol_types.html" >}}
+Message versions marked as flexible use the compact encoding for
variable-length fields. In particular, arrays use `COMPACT_ARRAY` rather than
`ARRAY`; strings and byte arrays similarly use their corresponding `COMPACT_*`
types. Compact encodings store their length as an unsigned variable-length
integer instead of a fixed-width integer. Flexible versions also include a
tagged-fields section at the end of every request and response component.
+
### Notes on reading the request format grammars
The [BNF](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form)s below give
an exact context free grammar for the request and response binary format. The
BNF is intentionally not compact in order to give human-readable name. As
always in a BNF a sequence of productions indicates concatenation. When there
are multiple possible productions these are separated with '|' and may be
enclosed in parenthesis for grouping. The top-level definition is always given
first and subsequent sub-parts [...]
