[ https://issues.apache.org/jira/browse/AVRO-438?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Doug Cutting updated AVRO-438: ------------------------------ Resolution: Fixed Fix Version/s: 1.3.1 Assignee: Amichai Rothman Hadoop Flags: [Reviewed] Status: Resolved (was: Patch Available) I just committed this. Thanks, Amichai! Let's address the other improvements you've suggested in new issues, okay? > spec organization and clarification improvements > ------------------------------------------------ > > Key: AVRO-438 > URL: https://issues.apache.org/jira/browse/AVRO-438 > Project: Avro > Issue Type: Improvement > Components: spec > Affects Versions: 1.3.0 > Reporter: Amichai Rothman > Assignee: Amichai Rothman > Priority: Trivial > Fix For: 1.3.1 > > Attachments: fix_spec_loose_ends.patch > > > There are a few improvements that can be made to make the spec better > organized and clarify ambiguous meanings: > 1. The binary encoding specifies string, then bytes, then longs. However, the > first two are dependent on the latter, so in essence long encoding is being > used before it was defined. In addition, string comes before bytes even > though it is logically a special case of bytes. It would be clearer if these > were ordered long, bytes, string so that each definition builds on its > predecessors and nothing is used before it is defined. Maybe bytes/string > should be at the end of the other primitives, since they are technically more > complex structures. Note that it might be a good idea to do this in all > places in the spec where primitives are enumerated. > 2. The sentence about array count and size is a bit confusing. A possible > alternative: > "If a block's count is negative, its absolute value is used, and it is > followed immediately by a long block size indicating the number of bytes in > the block. " > and maybe this should be immediately followed by the sentence explaining why > this is useful which is currently a few lines below. > 3. There is a note about blocks being in experimental stage, but it's unclear > if this is only for map blocks or also for array blocks. > 4. Object Container Files and Protocol Declarations are described in the spec > using JSON objects and their schema is shown, but it doesn't say anywhere how > these should be serialized. If it's using binary serialization, it should say > so explicitly. If it can be either binary or JSON, then the file has no > self-describing way of differentiating the two - this should be addressed > somewhere (maybe have a different magic word for binary/JSON content). > 5. Protocol Definition has a namespace and name (called protocol), but it is > not clear whether the namespace rules defined in the first section apply here > or not. It should be mentioned explicitly either way. > 6.It would be extremely helpful to have a full sample of an RPC call over > HTTP, possibly using the HelloWorld protocol from the previous example. This > would show how the transport, framing, handshake, call format and messages > all fit together. Examples in RFCs often help clarify any misunderstandings > that might arise from the body of the specs, which makes for a better spec - > and this would be great here too. -- This message is automatically generated by JIRA. - You can reply to this email to add a comment to the issue online.