W3C home > Mailing lists > Public > ietf-http-wg@w3.org > October to December 2009

Re: suggestions for examples and explication wrt ABNF and header fields in draft-ietf-httpbis-p1

From: Julian Reschke <julian.reschke@gmx.de>
Date: Tue, 29 Dec 2009 15:59:44 +0100
Message-ID: <4B3A1960.9070209@gmx.de>
To: =JeffH <Jeff.Hodges@KingsMountain.com>
CC: IETF HTTP WG <ietf-http-wg@w3.org>
=JeffH wrote:
> Hi, below are some modest suggestions for sections 1.2.1, 1.2.2, and 3.2 
> in draft-ietf-httpbis-p1-messaging-08 wrt the description of the ABNF 
> rules and header fields. I believe adding such examples and prose will 
> help one to figure things out more easily. I went through such an 
> exercise last week (I based a new version of the 
> Strict-Transport-Security header field on httpbis grammar), and it would 
> have been somewhat easier if httpbis-p1 contained the below enhancements.
> 
> thanks, HTH,
> 
> =JeffH
> ------

Thanks Jeff,

comments in-line...:

> [composed for a fixed-pitch font]
> 
> in draft-ietf-httpbis-p1-messaging-08:
> -------------------------------------
> 
> It would be helpful if there were some examples inserted into the below 
> subsection, as well as enhancing the first two paragraphs..
> 
>  > 1.2.1.  ABNF Extension: #rule
>  >
>  >    One extension to the ABNF rules of [RFC5234] is used to improve
>  >    readability.
> 
> replace above para:
> 
>      The #rule extension to the ABNF rules of [RFC5234] is used to
>      improve readability.

Ok.

> 
>  >    A construct "#" is defined, similar to "*", for defining lists of
>                                                              ^
>                                                         comma-delimited
> 
>  >    elements.  The full form is "<n>#<m>element" indicating at least <n>
>  >    and at most <m> elements, each separated by a single comma (",") and
>  >    optional whitespace (OWS).
>                              ^
>                      see Section 3.2

Ok, except I think the reference needs to go to 1.2.2.

>  >    Thus,
>  >
>  >      1#element => element *( OWS "," OWS element )
>  >
>  >    and:
>  >
>  >      #element => [ 1#element ]
>  >
>  >    and for n >= 1 and m > 1:
>  >
>  >      <n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element )
> 
> insert:
> 
>      For example, given these ABNF productions:
> 
>         example-list = 1#example-list-elmt
> 
>         example-list-elmt = token  ; see Section 3.2
> 
> 
>      Then these are legitimate values for example-list (not including
>      the double quotes, which are present for delimitation only):
> 
>         "foo,bar"
> 
>         " foo ,bar"
> 
>         "  foo , bar,charlie   "
> 
>         "foo ,bar,   charlie "
> 
>         etc.
> 
> 
>  >    For compatibility with legacy list rules, recipients SHOULD accept
>  >    empty list elements.  In other words, consumers would follow the list
>  >    productions:
>  >
>  >      #element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
>  >
>  >      1#element => *( "," OWS ) element *( OWS "," [ OWS element ] )
>  >
>  >    Appendix C shows the collected ABNF, with the list rules expanded as
>  >    explained above.
> 
> insert:
> 
>      For example, given the  example-list ABNF production above, these
>      are also legitimate values for example-list (again, (not including
>      the double quotes, which are present for delimitation only):
> 
>         "foo,bar,"
> 
>         ",,,,foo,,,,,bar,,,,,,"
> 
>         ",foo,bar"
> 
>         etc.

I agree that examples are needed for everyone not familiar with the 
history of this. That being said, I have re-arranged stuff so that the 
valid examples include empty elements, and I also added examples for 
invalid values. (See below).


> A suggested prose enhancement for "1.2.2.  Basic Rules"..
> 
>  >
>  > 1.2.2.  Basic Rules
>  >
>  >    HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
>  >    protocol elements except the entity-body (see Appendix A for tolerant
>  >    applications).  The end-of-line marker within an entity-body is
>  >    defined by its associated media type, as described in Section 2.3 of
>  >    [Part3].
>  >
>  >    This specification uses three rules to denote the use of linear
>  >    whitespace: OWS (optional whitespace), RWS (required whitespace), and
>  >    BWS ("bad" whitespace).
> 
> insert new para:
> 
>      This specification also uses the ABNF rule name prefix "obs-" to
>      denote "obsolete" grammar rules that appear for historical reasons:
>      obs-fold, obs-text, and obs-date. Please refer to section 3.2 for
>      further information concerning the first two, and section 6.1 for
>      obs-date.

I'd like to avoid enumerating these; the set may change after all... SO 
I have simply added an explanation of the "obs-" prefix to 1.2.


>  >    The OWS rule is used where zero or more linear whitespace characters
>  >    ...
> 
> 
> 
> WRT "3.2    Header Fields"..
> 
>  > 3.2.  Header Fields
>  >
>  >    Each HTTP header field consists of a case-insensitive field name
>  >    followed by a colon (":"), optional whitespace, and the field value.
>  >
>  >      header-field   = field-name ":" OWS [ field-value ] OWS
>  >      field-name     = token
>  >      field-value    = *( field-content / OWS )
>  >      field-content  = *( WSP / VCHAR / obs-text )
>  >
>  >    No whitespace is allowed between the header field name and colon.
>  >    For security reasons, any request message received containing such
>  >    whitespace MUST be rejected with a response code of 400 (Bad
>  >    Request).  A proxy MUST remove any such whitespace from a response
>  >    message before forwarding the message downstream.
>  >
>  >    A field value MAY be preceded by optional whitespace (OWS); a single
>  >    SP is preferred.  The field value does not include any leading or
>  >    trailing white space: OWS occurring before the first non-whitespace
>  >    character of the field value or after the last non-whitespace
>  >    character of the field value is ignored and SHOULD be removed without
>  >    changing the meaning of the header field.
> 
> 
> I suggest adding, right here after the above paragraph, some example 
> header fields. At least one should feature comma-separated field-values. 
> e.g.
> 
> 
>      example-header1: foo
> 
>      example-header2:foo
> 
>      example-header3: foo=bar,barfoo;attrib,charlie
> 
>      etc.

...I will look at this later on.

I just committed <http://tools.ietf.org/wg/httpbis/trac/changeset/738>.

1.2 and 1.2.1 now read:

-- snip --
1.2.  Syntax Notation

    This specification uses the Augmented Backus-Naur Form (ABNF)
    notation of [RFC5234].

    The following core rules are included by reference, as defined in
    [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF
    (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote),
    HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit
    sequence of data), SP (space), VCHAR (any visible [USASCII]
    character), and WSP (whitespace).

    As a syntactical convention, ABNF rule names prefixed with "obs-"
    denote "obsolete" grammar rules that appear for historical reasons.

1.2.1.  ABNF Extension: #rule

    The #rule extension to the ABNF rules of [RFC5234] is used to improve
    readability.

    A construct "#" is defined, similar to "*", for defining comma-
    delimited lists of elements.  The full form is "<n>#<m>element"
    indicating at least <n> and at most <m> elements, each separated by a
    single comma (",") and optional whitespace (OWS, Section 1.2.2).

    Thus,

      1#element => element *( OWS "," OWS element )

    and:

      #element => [ 1#element ]

    and for n >= 1 and m > 1:

      <n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element )

    For compatibility with legacy list rules, recipients SHOULD accept
    empty list elements.  In other words, consumers would follow the list
    productions:

      #element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ]

      1#element => *( "," OWS ) element *( OWS "," [ OWS element ] )

    Note that empty elements do not contribute to the count of elements
    present, though.

    For example, given these ABNF productions:

      example-list      = 1#example-list-elmt
      example-list-elmt = token ; see Section 1.2.2

    Then these are valid values for example-list (not including the
    double quotes, which are present for delimitation only):

      "foo,bar"
      " foo ,bar,"
      "  foo , ,bar,charlie   "
      "foo ,bar,   charlie "

    But these values would be invalid, as at least one non-empty element
    is required:

      ""
      ","
      ",   ,"

    Appendix C shows the collected ABNF, with the list rules expanded as
    explained above.
-- snip --

Feedback appreciated,

Julian
Received on Tuesday, 29 December 2009 15:00:30 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 27 April 2012 06:51:14 GMT