Subject: Editorial styling inconsistencies when referring to Structured Fields

From: Lucas Pardue <[email-masked]>
Date: Wed, 16 Feb 2022 20:53:44 +0000

Hey all,

I'm a big fan of Structured Fields. They make a lot of things easier.
However, I'm finding some editorial difficulties when working on documents
that define HTTP Fields in a structured fields format. An ad-hoc survey of
some of the active documents in this WG and elsewhere seem to show an
inconsistent editorial approach. I've not even been consistent myself.

To illustrate what I mean. Let's consider the types in Structured fields,
I'll call these descriptors: List, Inner List, Parameters, Dictionaries,
Item (of bare-item type Integer, Decimal, String, Token, Byte Sequence,
Boolean). List, Inner List, and Dictionary contain Item(s). These types
have the respective ABNF: sf-list, inner-list, parameters, sf-dictionary,
sf-item (of bare-item time sf-integer, sf-decimal, sf-string, sf-token,
sf-binary, sf-boolean).

In the documents that use Structured Fields, there seems to be a mixed bag
of usage of the descriptor format (e.g. Dictionary) and the ABNF format
(e.g. sf-dict) in the prose. A common pattern seems to be, to declare the
container type as Dictionary or List and then the contents of the
dictionary using ABNF. This is especially important because the collections
contain Item, and specs often need to subset Item to a specific type like
Integer or Byte Sequence. That also leads to an annoying construct like

> Foo-Field is a Structured Fields List. List members MUST be of type
sf-string. No parameters are defined.
> Foo-Field: sf-list

I wonder if anyone else feels the inconsistency is off-putting and or
distracting when trying to write or read specs. Should we attempt to define
a consistent house style?

Cheers,
Lucas

---

From: Roberto Polli <[email-masked]>
Date: Wed, 16 Feb 2022 22:36:47 +0100

Strongly agree.

I fought with that a bit in
https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-02.html

where I used sf- and abnf as building blocks to further define field syntax

My2c,
R

Il mer 16 feb 2022, 21:56 Lucas Pardue <[email-masked]> ha

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 17 Feb 2022 09:27:58 +1100

I wasn't terribly happy about including ABNF in SF, but IIRC some really wanted it because it's expected for HTTP headers. *shrug*

I'd recommend avoiding it if possible, or at least only using it in separate ABNF blocks (not prose).

Cheers,

> On 17 Feb 2022, at 7:53 am, Lucas Pardue <[email-masked]> wrote:
> 
> Hey all,
> 
> I'm a big fan of Structured Fields. They make a lot of things easier. However, I'm finding some editorial difficulties when working on documents that define HTTP Fields in a structured fields format. An ad-hoc survey of some of the active documents in this WG and elsewhere seem to show an inconsistent editorial approach. I've not even been consistent myself.
> 
> To illustrate what I mean. Let's consider the types in Structured fields, I'll call these descriptors: List, Inner List, Parameters, Dictionaries, Item (of bare-item type Integer, Decimal, String, Token, Byte Sequence, Boolean). List, Inner List, and Dictionary contain Item(s). These types have the respective ABNF: sf-list, inner-list, parameters, sf-dictionary, sf-item (of bare-item time sf-integer, sf-decimal, sf-string, sf-token, sf-binary, sf-boolean). 
> 
> In the documents that use Structured Fields, there seems to be a mixed bag of usage of the descriptor format (e.g. Dictionary) and the ABNF format (e.g. sf-dict) in the prose. A common pattern seems to be, to declare the container type as Dictionary or List and then the contents of the dictionary using ABNF. This is especially important because the collections contain Item, and specs often need to subset Item to a specific type like Integer or Byte Sequence. That also leads to an annoying construct like
> 
> > Foo-Field is a Structured Fields List. List members MUST be of type sf-string. No parameters are defined.
> > 
> > Foo-Field: sf-list
> 
> I wonder if anyone else feels the inconsistency is off-putting and or distracting when trying to write or read specs. Should we attempt to define a consistent house style?
> 
> Cheers,
> Lucas

--
Mark Nottingham   https://www.mnot.net/

---

From: Lucas Pardue <[email-masked]>
Date: Wed, 16 Feb 2022 22:41:47 +0000

Hey Mark,

On Wed, 16 Feb 2022, 22:28 Mark Nottingham, <[email-masked]> wrote:

> I wasn't terribly happy about including ABNF in SF, but IIRC some really
> wanted it because it's expected for HTTP headers. *shrug*
>

I can get behind that. Although I'll note that proxy-status has 29
instances in prose and priorities has 2. Maybe we should fix these up as
part of AUTH48, in order to set some consistent examples?

Cheers
Lucas

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 17 Feb 2022 09:46:15 +1100

Huh. Never said *I* had to be consistent :)

Yeah, that seems like a good idea. I've opened:
  https://github.com/httpwg/http-extensions/issues/1974

Thanks,

> On 17 Feb 2022, at 9:41 am, Lucas Pardue <[email-masked]> wrote:
> 
> Hey Mark,
> 
> I can get behind that. Although I'll note that proxy-status has 29 instances in prose and priorities has 2. Maybe we should fix these up as part of AUTH48, in order to set some consistent examples?
> 
> Cheers
> Lucas

---

From: Roberto Polli <[email-masked]>
Date: Thu, 17 Feb 2022 15:28:48 +0100

Hi Mark & al.

>   https://github.com/httpwg/http-extensions/issues/1974

SF achieves the goal of associating types to each field part, but it relies
on prose - which is subject to interpretation - to describe relations
between all those parts.

ABNF is limited to syntax, but it's formal and can be used to
label single field parts and compose them... maybe we should identify
some conventions to express those relations with SF too.

An "exercise" in SF could be to express Accept-Encoding
https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#rfc.section.12.5.3
accordingly to https://github.com/httpwg/http-extensions/issues/1974
without using abnf:  which would be the result?

Have a nice day,
R.

---

From: Lucas Pardue <[email-masked]>
Date: Thu, 17 Feb 2022 14:59:52 +0000

Hey,

> some conventions to express those relations with SF too.

SF makes it possible to avoid needing to do that, which I see as a positive
outcome a lot of the time. Rather than needing to invent custom terms for a
custom header's list members, I just point at SF List member. However, it's
not always simple

> without using abnf:  which would be the result?

Retrofit headers classes these as an SF List [1]. If we wanted to be more
expansive about a definition, my first suggestion would be

"The Accept-Encoding header field is an SF List. Members are SF Token where
the value is a name from the HTTP Content Coding Registry. The SF Parameter
"q" is defined, the value is SF Decimal representing a quality weighting."

This seems concise and self contained. The one downside is where there is
commonality between fields, such as `content-coding` or `qvalue` (that we
discussed in relation to digest). Here what you might want to do is invent
a Structured Fields typedef that can act as syntactic sugar. In other words:

""SF Content Coding" is an SF Token when the value is a name from the HTTP
Content Coding Registry"
snip
"The Accept-Encoding header field is an SF List; members are SF Content
Coding."
snip
"The Content-Encoding header field is an SF Item of type SF Content Coding."

I'm sure there are many other ways to do this, some more open to
interpretation than not.

Cheers,
Lucas

[1]
https://mnot.github.io/I-D/draft-nottingham-http-structure-retrofit.html#name-compatible-fields

---

From: Roberto Polli <[email-masked]>
Date: Thu, 17 Feb 2022 23:16:45 +0100

Hi Lucas,

Il gio 17 feb 2022, 16:00 Lucas Pardue <[email-masked]> ha
scritto:

> "The Accept-Encoding header field is an SF List. Members are SF Token
> where the value is a name from the HTTP Content Coding Registry. The SF
> Parameter "q" is defined, the value is SF Decimal representing a quality
> weighting."
>
> ... where there is commonality between fields, ... a Structured Fields
> typedef that can act as syntactic sugar.
>

I think that's something useful, and that we should work out.

> ""SF Content Coding" is an SF Token when the value is a name from the HTTP

Side note: the prose would be longer, since "identity" and "*" token are
allowed value outside the content coding registry.
With abnf you get it at first sight, and that "first sight" feature is
probably something we should provide with SF even if we want to get rid of
abnf.

My2c,
R

snip

---

From: Lucas Pardue <[email-masked]>
Date: Thu, 17 Feb 2022 22:50:20 +0000

Hey

On Thu, 17 Feb 2022, 22:16 Roberto Polli, <[email-masked]> wrote:

>> ""SF Content Coding" is an SF Token when the value is a name from the
>> HTTP Content Coding Registry"
>>
>

Right. I omitted them becauase I was being lazy but it would be simple
enough to say "Members are SF Token where the value is a name from the HTTP
Content Coding Registry, or "identity", or "*"."

Having a common way to express constraints can make the work of an
implementer, who has to translate the spec into code, a bit more rigmarole.
In this case, boring is good. In my experience, having ABNF wouldn't help
me much because I consume it all as text anyway. I wouldn't do a hard sell
on my suggestions of terminology, I'm sure the other HTTP and RFC gurus
that have a better suggestion.

Cheers
Lucas