Hello! Yes, it looks like `fixed` is the only named complex type that doesn't have a doc attribute. No primitive types have the doc attribute.
This might be an omission, but I don't think it's inconsistent. In my experience, there's no compelling reason to document schemas of primitive types, but a good practice for the fields or container types that they're inside. Fixed is not a primitive type, but in practice it's used like bytes (which is). In my opinion, I wouldn't consider it important to make the doc attribute universal on any type/field, but I wouldn't have any strong objection if that were the consensus. Today, I'm pretty sure that the Java implementation corresponds to the spec with regards to the doc attribute. As a minimum, I'd propose that the only action here is to change the IDL guide: "Comments that begin with /** are used as the documentation string (if applicable) for the type or field definition that follows the comment." Is this what you're looking for? All my best, Ryan P.S. I'm very intrigued by the "thorough schema compliance checker"! Is this something that would be shared? Would it help find other inconsistencies in the Avro spec and implementations? On Fri, Dec 6, 2019 at 4:49 PM Jonah H. Harris <jonah.har...@gmail.com> wrote: > > Hey, everyone. > > After encountering a number of issues arising from the use of various Avro > encoder/decoder implementations, each with a varying degree of specification > compliance, I've begun implementing a thorough schema compliance checker. > While going through the specification, however, I believe there's an > inconsistency: the documentation for fixed types omits an optional doc > attribute. > > Given the type, and its similarity to other like-types, this omission doesn't > seem to make sense. Likewise, the overall Avro specification appears to > conflict with the IDL specification, which states, "Comments that begin with > /** are used as the documentation string for the type or field definition > that follows the comment." In this case, it seems a doc attribute is valid > for all type/field definitions, including fixed types. > > If I'm misunderstanding this inconsistency, please let me know. Otherwise, if > doc is a valid attribute for any type/field definition, can the specification > be updated appropriately? > > While I also posted this to dev list, that seems to contain more Jira-related > updates than discussion. Also, I didn't think this inquiry warranted a Jira > ticket. As this is something I'm working on to enable our engineering team to > move forward with Avro as our common serialization format, time is of the > essence. All ideas/suggestions are appreciated. > > -- > Jonah H. Harris >
