[jira] [Created] (KAFKA-17865) Protocol documentation field names are sometimes ambiguous

["Andrew Schofield (Jira)" <ji...@apache.org>]

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)