Subject: Re: [apps-discuss] review of draft-bormann-cbor-04

From: ray polk <[email-masked]>
Date: Sat, 10 Aug 2013 15:02:36 -0600

I have been selected as the Applications Area Review Team reviewer for 
this draft.  For background on apps-review, please see 
http://www.apps.ietf.org/content/applications-area-review-team

Document: draft-bormann-cbor-04
Title: Concise Binary Object Representation (CBOR)
Reviewer: Ray Polk
Review Date: 10 August 2013

Summary: This draft is ready for publication as a Proposed Standard.

Major Issues:
- none -- After pouring over the binary/hex and the mapping to/from 
json, I couldn't find a single mistake.  It meets its objectives and 
addresses the primary issues of msgpack (extensibility,  open standard, 
different types for string and byte streams)

Minor Issues:
- none

Editorial / Nits:
2.
- Consider striking "For the impatient reader," or rephrasing for tone.
- Consider referring to the type section after "...the major type (the 
high-order 3 bits)..." ?
- "Every item between the byte string with the indefinite length 
indicator and..."
Consider something like "...CBOR item with type byte string..." ?

2.3.
- Consider swapping the last two paragraphs; providing detail about 
simple type before discussing floating point (to match order laid out in 
Table 1).

2.4.
- consider continuing the use of "preceded by" as found in the first 
sentence; perhaps eliminating the "enclosed by" phrasing.  use of the 
term "enclosed by" implies a closing "break" or closing tag.
- "A secondary purpose it to allow..." > "A secondary purpose is to 
allow..."
- consider using MAY in this section to highlight its optional nature.

2.4.3.
- consider breaking up the run-on sentence that begins:  "An example of 
a decimal fraction is that the number 273.15..."

3.
- Much of section 3 could be condensed (or even moved into an 
informational RFC?).  It's a little verbose/redundant.  The most helpful 
bits are obfuscated/diluted by the less helpful ones.

For example, sections 3.2.2 & 3.2.3. are redundant.  consider making 
them one paragraph instead of three:

A parser may come across a simple value Section 2.3 or a tag Section 2.4 
that it does not recognize, such as a value that was added to the IANA 
registry after the parser was deployed or a value that the parser chose 
not to implement.  Further, a parser might or might not want to verify 
that the sequence of bytes in an UTF-8 string (major type 3) is actually 
valid UTF-8.  In these cases, the parser might issue a warning, might 
stop processing altogether, might handle the error and make the 
incorrectly-typed value available to the application as such, or take 
some other type of action.

I think similar improvements could be made to other 3.x subsections.

Appendix E
The draft states, "BSON specification is 'baroque,' clouded by 
requirements for DB" -- consider adding a corresponding objective that 
this violates and citing it here.

>     On 7/17/2013 1:25 PM, Ray Polk wrote:
>
>         I will complete a review by August 9th. Regards, Ray -----
>         Original Message ----- From: [email-masked] To:
>         [email-masked] Cc: [email-masked] Sent: Wednesday, July
>         17, 2013 11:45:17 AM GMT -07:00 US/Canada Mountain Subject:
>         review of draft-bormann-cbor-04 Hello Ray, could you please
>         perform a review of draft-bormann-cbor-04 by August 13th
>         (which is the LC end date) ? Please let us know and ack !
>         thanks indeed and all th best!
>         ------------------------------------------------------------------------
>         Claudio Allocchio G A R R [email-masked] Senior T!
>         echnical Officer tel: +39 040 3758523 Italian Academic and
>         G=Claudio; S=Allocchio; fax: +39 040 3758565 Research Network
>         P=garr; A=garr; C=it; PGP Key:
>         http://www.cert.garr.it/PGP/keys.php3#ca
>
>

---

From: Paul Hoffman <[email-masked]>
Date: Sat, 10 Aug 2013 15:49:52 -0700

Thanks for the review! Many of your editorial clarifications will appear in the -05.

--Paul Hoffman