[jira] Commented: (AVRO-438) spec organization and clarification improvements

["Doug Cutting (JIRA)" <ji...@apache.org>]

    [ 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.