Structured Field Values for HTTP
draft-ietf-httpbis-header-structure-19

Overall, several questions I had while reading the first time were answered,
either directly or implicitly, by text that followed.

[[ questions ]]

* It's documented as possible for field definitions to place constraints on
  cardinality; what about constraints on order as well in certain situations?

  This came to mind again when I got to section 3.2 and read that index-based
  access was required for dictionaries.  Is it possible for a field definition
  to place requirements on the order of things in a dictionary?

  The phrase "ordered <thing>" appears repeatedly, and Appendix B has important
  notes about order-preserving structures.  Did I perhaps miss some text early
  on about this, or should/could this be highlighted in non-appendix text?

* [ section 4.1.2 ]
  Should items 3, 3.1, .. 5.2 be indented and renumbered under 2 after 2.1?

* [ section 4.1.8 ]
  Just to confirm: does serializing an empty byte sequence result in ::?
  (assuming a context where the entire structured field would not otherwise
  have been left unserialized)

  My reading of 4.2.7 is that :: would parse correctly as a 0-length byte
  sequence.

[[ random ]]
* The named ABNF productions are all sh-*, which I assume is for "structured
  header".  I assume it's too late at this point, but sf-* for "structured
  field" seemed like a logical choice to me.  Not the least bit important,
  though!

Thanks for this work.

I support Benjamin's DISCUSS point about case sensitivity especially with respect to how a consumed dictionary should be used.  It's fine if you want to say that the rules for key matching are left to the authors of specifications of future structured fields, but if that's the case, please do say so.

Should Section 3.1 be explicit that lists are ordered?  It does say "array" but some definitions I found for that term don't explicitly say anything about order either, just a "collection".

As my colleagues have already done a rather thorough job, all I have left is a few nits:

Nits:

Section 3.1.2:
* "... key-values pairs ..." -- s/values/value/

Section 3.2:
* First paragraph, two instances of "items" should be capitalized.
* "Note that dictionaries ..." -- capitalize "dictionaries"
* "... Inner List of tokens:" -- capitalize "tokens"
* "A Dictionary with a mix of singular and list values ..." -- capitalize "list", and maybe "Item" instead of "singular"?

Thanks for explaining the parsing algorithms in my earlier DISCUSS points.
====
** Section 4.1. Reading steps 1 – 6 like pseudo-code, if Step 1 is true, output_string will be undefined in Step 6.    There needs to be a step 0 which reads “Let output_string be an empty string” or Step 1 needs to explicitly initialize output_string.

** Section 4.1.8.  Per Step 1, “If input_bytes is not a sequence of bytes, fail serialization”, what input wouldn’t be considered as sequence of bytes?

** Section 4.2.  An algorithmic style nit.  In Section 4.1, the text used an “IF x ELSE IF y ELSE IF z ELSE fail” convention.  Here the text is a series of simple “IF x; IF y; IF z; …” statements.

** Section 4.2.  Editorial.  In step 8, s/Otherwise, return output./Else, return output./

The document starts with "Specifying the syntax of new HTTP header (and trailer) fields is an onerous task; even with the guidance in Section 8.3.1 of [RFC7231], there are many decisions - and pitfalls - for a prospective HTTP field author." -- having never done this, I'll just have to take the authors' word on this. I'm balloting NoObj in the "This is outside my area of expertise, but it is interesting" sense :-)

Thank you for the work put into this document. The document is easy to read. And I loved the good old ASCII scissors "--8<--"

Please find below a couple on non-blocking COMMENTs.

I hope that this helps to improve the document,

Regards,

-éric

== COMMENTS ==

-- Section 1 --
In the sentence "the mechanisms described herein are only intended to be used with those that explicitly opt into them.", does "those" mean "existing HTTP header" or "header", this little ambiguity should be lifted.
   
-- Section 4.1.2 --
Wow, I am impressed that nowadays, even a dictionary is sent as an HTTP header. (just a plain comment of mine even if an example would be useful for me).

Per the Gen-ART review, it seems like at a minimum the options available for integers larger than 10^15 should be noted somewhere so that readers are alert to it, even if no particular option is recommended.

Thank you for addressing my discuss (and comment!) points, and explaining
in cases where they were non-issues.

I do wonder whether (In Sections 3.3.1 and 3.3.2) it might be better to say
"might not be preserved" rather than "may not be preserved", though it
hopefully doesn't matter.

Thanks for addressing my issues and responding to comments. I have cleared.

== Discuss resolved, as have these nits below.

Thanks for this noble attempt to tame the wildness that is the HTTP spec!

Comments:
- While this is by no means a required change to publish this document, I found the order of Section 3 to be backwards from what would easiest to follow. The higher-order concepts (e.g. lists) are defined first, and refer to low-level concepts (like items) that are not defined till the end of the section.

Nits:
- In Sec 3.1.2, it might be useful to explain that in example-IntHeader, a is TRUE.

- sec 3.2. Can you add some text to make it clear that the value in dictionary entries is only optional (in brackets) because of Boolean TRUE? This was not clear to me until I read sec. 4.1.2.

- Sec 4. s/before HPACK is applied/before compression with HPACK
(A receiver "applies" HPACK to decompress, and presumably before doing this parsing)

- Sec 4.2. s/header value/field value

Hi,

Thank you for writing this document.  As per the other comments, more effort to have a tighter specification of HTTP header fields is likely to be beneficial, particularly if there are readily usable open source libraries that implement these.

However, my main comment (which possibly could have been a discuss) questions how this is specified.  In my experience other specifications of encodings define exactly what the format the encoding must take, but leave it up to implementation to decide how to perform that encoding.  Whereas this document specifies the format in 3 ways: (i) as a prose description of the format, (ii) as an ABNF description of the format, (iii) as a pair of algorithms that construct or parse the format.  I would prefer for the ANBF to be definitive along with prose to describe/refine the ANBF as required.  For the algorithms, I would have preferred that they are held in the appendix as non-normative text that provides a description of one possible method of writing the serialization or parsing code.  The corner cases that the algorithm cover could be in the normative prose/ABNF description.  I appreciate that this would be a significant change to the document and hence will leave it to authors/responsible AD to decide whether to process or ignore this comment.

A few other comments on particular sections that I noted:

1.2.  Notational Conventions

   When parsing from HTTP fields, implementations MUST follow the
   algorithms, but MAY vary in implementation so as the behaviors are
   indistinguishable from specified behavior.
   
I find that sentence slightly strange in that the first part of the sentence states that your MUST follow the algorithm, and the second part states that you don't have to follow the algorithm.  It might be more clear if this was worded differently.  E.g. MUST have behavior that is indistinguishable from that produced by the algorithm.

3.1  Lists:

   An empty List is denoted by not serializing the field at all.
   
This was slightly unclear to me.  Does this mean that it isn't possible to distinguish between not providing the header and providing an empty list?  Possibly it might be worth clarifying this here, although I note that it does become clear what the expected behavior is later in the document.

3.2.  Dictionaries

   Dictionaries are ordered maps of name-value pairs, where the names
   are short, textual strings
  
"short, textual" => short textual"
   
It might also be helpful to explicitly state what the ordering is (i.e. I presume that it is the order that they are listed in the request)

3.3.1 Integers
Are "00" "01" "-0", "-01" all allowed?

3.3.6.  Booleans
Should this cover the fact that if the boolean value is not present it is interpreted as true in a parameter or dictionary?  E.g. as per the description in the parameter and dictionaries sections?

Regards,
Rob