[
https://issues.apache.org/jira/browse/AVRO-438?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Amichai Rothman updated AVRO-438:
---------------------------------
Attachment: fix_map_verboseness.diff
np :-)
Here's a patch which reduces the apparent complexity of map encoding
(previously several paragraphs copy&pasted from array encoding description), if
you like it. I think it's shorter to read and simpler to understand. It's just
semantics, so I've attached it here - I'll open a separate report for the mime
type issue.
> 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_map_verboseness.diff, 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.
