[
https://issues.apache.org/jira/browse/AVRO-438?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12840402#action_12840402
]
Doug Cutting commented on AVRO-438:
-----------------------------------
These generally sound like good changes. Would you like to construct a patch
for doc/src/content/xdocs/spec.xml?
> There is a note about blocks being in experimental stage [ ... ]
I think that's no longer the case and that note should probably be removed.
> it doesn't say anywhere how these should be serialized
Good catch. Both files and RPC only permit binary encoding at present.
> it is not clear whether the namespace rules defined in the first section
> apply here
Yes, they do.
> It would be extremely helpful to have a full sample of an RPC call over HTTP
> [ ... ]
Good idea. Although it might be rather opaque, since much would be binary.
> 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
> Priority: Trivial
>
> 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.
