Subject: making up new header field syntax...

From: Julian Reschke <[email-masked]>
Date: Sun, 25 Jun 2017 13:52:37 +0200

Here's a recent example I found (when looking for uses of JFV):

<https://w3c.github.io/webappsec-clear-site-data/#header>:

> The Clear-Site-Data HTTP response header field sends a signal to the user agent that it ought to remove all data of a certain set of types. The header is represented by the following ABNF [RFC5234]:
> 
> Clear-Site-Data = 1#( DQUOTE ( data-type | extension-type ) DQUOTE )
> data-type = "cache" | "cookies" | "storage" | "executionContexts"
> extension-type = 1*( ALPHA | "-")
> ; #rule is defined in Section 7 of RFC 7230.
> ; DQUOTE and ALPHA are defined in Appendix B.1 of RFC 5234.

Issues:

a) the list rule is defined in RFC 7230, not RFC 5234

b) the syntax doesn't allow whitespace, but the examples use it

c) things look like quoted-strings, but aren't quoted-strings

d) tokens not allowed

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sun, 25 Jun 2017 13:57:43 +0200

On 2017-06-25 13:52, Julian Reschke wrote:
>> The Clear-Site-Data HTTP response header field sends a signal to the 
>> user agent that it ought to remove all data of a certain set of types. 
>> The header is represented by the following ABNF [RFC5234]:
>>

e) ABNF invalid ("|" instead of "/" - 
<https://www.youtube.com/watch?v=LbK-g8tKnoc>)

Best regards, Julian

---

From: Mike West <[email-masked]>
Date: Thu, 29 Jun 2017 12:56:08 +0200

>> Here's a recent example I found (when looking for uses of JFV):
Hey Julian! Thanks for pointing out these mistakes! I'd encourage you to
file bugs against the spec next time; I'm more likely to see them on GitHub
than here.

I originally planned for this header to use JFV, and have backed away from
it because of the ongoing discussions in this group about what the Syntax
of the Future(tm) should look like. That said, I do anticipate needing some
more structure in the values in the fairly near future (`"cookies"` is not
nearly granular enough for most use cases, as it turns out). Personally, I
still believe JSON is a reasonable fit for that kind of structure... :)

On that note, https://wicg.github.io/feature-policy/ is another example you
might be interested in skimming through.

>> The Clear-Site-Data HTTP response header field sends a signal to the user
>>> agent that it ought to remove all data of a certain set of types. The
>>> header is represented by the following ABNF [RFC5234]:
>>>
Do you mean the reference to the `#rule`? That link points to RFC 7230, as
does the text, and https://tools.ietf.org/html/rfc7230#section-1.2 includes
DQUOTE and ALPHA by reference to RFC 5234. Should we be pointing to RFC
7230 for those as well?

> b) the syntax doesn't allow whitespace, but the examples use it
I think `1#whatever` allows whitespace. That's my reading of
https://tools.ietf.org/html/rfc7230#section-7, but I'm (obviously!) not an
expert.

Would you be happier with something like `1#( quoted-string )`? I'd like to
specify the legal values so I can link to them later in the spec, but I
suppose that doesn't need to be done in the ABNF.

d) tokens not allowed
Can you clarify what you'd like to see?

> e) ABNF invalid ("|" instead of "/" - <https://www.youtube.com/watch
> ?v=LbK-g8tKnoc>)
>

My mistake. Perhaps we should wire Bikeshed up to an ABNF validator. Added
a note to https://github.com/tabatkins/bikeshed/issues/459 to that effect.

-mike

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Jun 2017 13:18:50 +0200

On 2017-06-29 12:56, Mike West wrote:
> On Sun, Jun 25, 2017 at 1:57 PM, Julian Reschke <[email-masked] 
> <mailto:[email-masked]>> wrote:
> 
> file bugs against the spec next time; I'm more likely to see them on 
> GitHub than here.
> ...

It was intended to get us back to work on this :-)

> I originally planned for this header to use JFV, and have backed away 
> from it because of the ongoing discussions in this group about what the 
> Syntax of the Future(tm) should look like. That said, I do anticipate 
> needing some more structure in the values in the fairly near future 
> (`"cookies"` is not nearly granular enough for most use cases, as it 
> turns out). Personally, I still believe JSON is a reasonable fit for 
> that kind of structure... :)

So do I, if only for the reason that we're not making progress on the 
other solution, and *not* using JFV seems to do actual harm right now...

> On that note, https://wicg.github.io/feature-policy/ is another example 
> you might be interested in skimming through.

Saw that. See 
<https://www.greenbytes.de/tech/webdav/draft-reschke-http-jfv-06.html#rfc.section.B>.

>         <https://w3c.github.io/webappsec-clear-site-data/#header
>         <https://w3c.github.io/webappsec-clear-site-data/#header>>:
> 
>             The Clear-Site-Data HTTP response header field sends a
>             signal to the user agent that it ought to remove all data of
>             a certain set of types. The header is represented by the
>             following ABNF [RFC5234]:
> 
> Do you mean the reference to the `#rule`? That link points to RFC 7230, 
> as does the text, and https://tools.ietf.org/html/rfc7230#section-1.2 
> includes DQUOTE and ALPHA by reference to RFC 5234. Should we be 
> pointing to RFC 7230 for those as well?

I missed the reference in the comments part. Sorry. But no, this is 
*not* RFC5234-ABNF, so the introduction should be clearer on this. See, 
for instance, 
<https://www.greenbytes.de/tech/webdav/rfc7838.html#rfc.section.1.1>.

> https://tools.ietf.org/html/rfc7230#section-7, but I'm (obviously!) not 
> an expert.

You are right, sorry. Must have imagined some sub structure in the 
fields that isn't there right now.

> Would you be happier with something like `1#( quoted-string )`? I'd like 

That would be better.

> to specify the legal values so I can link to them later in the spec, but 
> I suppose that doesn't need to be done in the ABNF.

Exactly.

> Can you clarify what you'd like to see?

As long as this is just a list of keywords, you could just use a list of 
tokens (example: 
<https://www.greenbytes.de/tech/webdav/rfc7231.html#rfc.section.7.4.1>).

If you need or anticipate the need of keywords that aren't tokens (for 
instance, because of whitespace), I'd use

   token / quoted-string

>     <https://www.youtube.com/watch?v=LbK-g8tKnoc
>     <https://www.youtube.com/watch?v=LbK-g8tKnoc>>)
> 
> 
> My mistake. Perhaps we should wire Bikeshed up to an ABNF validator. 
> Added a note to https://github.com/tabatkins/bikeshed/issues/459 to that 
> effect.

Best regards, Julian

---

From: Mike West <[email-masked]>
Date: Thu, 29 Jun 2017 13:50:16 +0200

> other solution, and *not* using JFV seems to do actual harm right now...

I agree with you agreeing with me. :)

>> does the text, and https://tools.ietf.org/html/rfc7230#section-1.2
>> includes DQUOTE and ALPHA by reference to RFC 5234. Should we be pointing
>> to RFC 7230 for those as well?
>>
>
> I missed the reference in the comments part. Sorry. But no, this is *not*
> RFC5234-ABNF, so the introduction should be clearer on this. See, for
> instance, <https://www.greenbytes.de/tech/webdav/rfc7838.html#rfc.sect
> ion.1.1>.
>

I added some clarification along these lines in
https://github.com/w3c/webappsec-clear-site-data/commit/9f20dcc7580e241636c4787b6cf852a7e6258d63,
thanks!

>> Would you be happier with something like `1#( quoted-string )`? I'd like

Done (also in
https://github.com/w3c/webappsec-clear-site-data/commit/9f20dcc7580e241636c4787b6cf852a7e6258d63),
thanks!

> tokens (example: <https://www.greenbytes.de/tec
> h/webdav/rfc7231.html#rfc.section.7.4.1>).
>

Because I secretly expect to move back to JSON at some point in the future,
I'd prefer to require quoted-string, as that seems forward-compatible with
treating the header as a list of valid JSON objects. That is, `Header:
value, value, value` would explode in a JSON parser, while `Header:
"value", "value", "value"` would not.

-mike

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Jun 2017 13:55:19 +0200

On 2017-06-29 13:50, Mike West wrote:
> ...
> Because I secretly expect to move back to JSON at some point in the 
> future, I'd prefer to require quoted-string, as that seems 
> forward-compatible with treating the header as a list of valid JSON 
> objects. That is, `Header: value, value, value` would explode in a JSON 
> parser, while `Header: "value", "value", "value"` would not.
> ...

Oh, what a cunning plan - now it makes perfect sense :-)

But be aware that if you write

  "value"

in ABNF, it also matches "Value", "VALUE, "vALUE" etc - something you 
likely do not want in this case.

So you may have to invoke the ABNF-Extension defined in 
<https://tools.ietf.org/html/rfc7405>. Example in 
<https://www.greenbytes.de/tech/webdav/rfc7838.html#rfc.section.3>: 
"clear" production.

Best regards, Julian