Andrew Schofield created KAFKA-17865:
----------------------------------------
Summary: Protocol documentation field names are sometimes ambiguous
Key: KAFKA-17865
URL: https://issues.apache.org/jira/browse/KAFKA-17865
Project: Kafka
Issue Type: Improvement
Components: docs
Reporter: Andrew Schofield
The Kafka documentation includes a description of the Kafka protocol
([https://kafka.apache.org/protocol).] In some cases, particularly for tagged
fields, the table of fields contains duplicate entries with ambiguous names.
This is essentially because the schemas in the protocol have a hierarchical
structure, while the tables of fields flatten the names to only the last part
with no indication of the structure.
The names could be disambiguated in a couple of ways. First, there could be a
numbering schema for tagged fields. Second, the field names could follow their
true hierarchical structure.
Here's an example of the DescribeQuorum v0 request.
{noformat}
DescribeQuorum Request (Version: 0) => [topics] TAG_BUFFER
topics => topic_name [partitions] TAG_BUFFER
topic_name => COMPACT_STRING
partitions => partition_index TAG_BUFFER
partition_index => INT32{noformat}
Today, all three of the TAG_BUFFER fields are just described as
"_tagged_fields", when really they are probably more like "_tagged_fields",
"topics[]._tagged_fields" and "topics[].partitions[]._tagged_fields". Of
course, simply numbering them would be equally unambiguous.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
