Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
...and, as the comment was about Parameters, my examples should look like: Example-Header: X; parm="1234" // sf-string Example-Header: X; parm=1234// sf-integer Example-Header: X; parm="foo123"// sf-string Example-Header: X; parm=foo123 // sf-token Example-Header: X; parm="1.2.3.4" // sf-string Example-Header: X; parm=1.2.3.4 // NOT a valid value, as sf-decimal only allows one dot Example-Header: X; parm="1.2" // sf-string Example-Header: X; parm=1.2 // sf-decimal Regards, Christer -Original Message- From: Gen-art On Behalf Of Christer Holmberg Sent: Monday, 22 May 2023 10.48 To: Mark Nottingham Cc: gen-art@ietf.org; HTTP APIs Working Group ; Last Call Subject: Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02 Hi Mark, >>> Ah. The reason is that allowing any type would require creating a >>> mapping of current values to SF types, and there are just too many >>> potential (and undocumented) values already in use to do this. >> >> I don't think that is true. Just because the Parameter syntax allows >> values to be encoded sf-string, sf-token, sf-boolean etc it doesn't >> mean that you have to map each value (existing or new ones) to each >> of those encodings. If a value is defined as a String, then it has to >> be encoded as a sf-string. > > Consider an implementation that wants to serialise a link relation > that has a 'foo' Parameter that it has no special knowledge of. If the > value is "bar", that's very straightforward -- it will successfully > serialise as a Token. However, consider the value "1.2.3.4" -- it will > fail parsing, because it looks like an Integer or Decimal to the > parser, but it isn't. It will not look like an Integer or Decimal to the parser: if the value is surrounded by quotes, it is a String. Tokens, Integers and Decimal do not have quotes. Example-Header: "1234" // sf-string Example-Header: 1234// sf-integer Example-Header: "foo123"// sf-string Example-Header: foo123 // sf-token Example-Header: "1.2.3.4" // sf-string Example-Header: 1.2.3.4 // NOT a valid value, as sf-decimal only allows one dot Example-Header: "1.2" // sf-string Example-Header: 1.2 // sf-decimal >Of course, we could specify something like "try to parse it as a >Structured Value; if serialisation fails, serialise it as a String." >That strategy might be workable, but it creates a lot of complexity -- >at runtime when you have to test the value by running code, and when >values are handled, because now they could come in multiple forms. > >Always serialising as a string recognises that, from the standpoint of >the Link header field, the value's type is opaque. In general, if a parser is not able to determine the encoding without "testing" values etc, the syntax is bad. But, in the case of structured field values that is not the case: the parser will always know if a value is sf-string, sf-integer, sf-decimal etc. Regards, Christer smime.p7s Description: S/MIME cryptographic signature ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
Hi Mark, >>> Ah. The reason is that allowing any type would require creating a >>> mapping of current values to SF types, and there are just too many >>> potential (and undocumented) values already in use to do this. >> >> I don't think that is true. Just because the Parameter syntax allows >> values to be encoded sf-string, sf-token, sf-boolean etc it doesn't >> mean that you have to map each value (existing or new ones) to each of >> those encodings. If a value is defined as a String, then it has to be >> encoded as a sf-string. > > Consider an implementation that wants to serialise a link relation that has > a 'foo' Parameter > that it has no special knowledge of. If the value is "bar", that's very > straightforward -- it will > successfully serialise as a Token. However, consider the value "1.2.3.4" -- > it will fail parsing, because > it looks like an Integer or Decimal to the parser, but it isn't. It will not look like an Integer or Decimal to the parser: if the value is surrounded by quotes, it is a String. Tokens, Integers and Decimal do not have quotes. Example-Header: "1234" // sf-string Example-Header: 1234// sf-integer Example-Header: "foo123"// sf-string Example-Header: foo123 // sf-token Example-Header: "1.2.3.4" // sf-string Example-Header: 1.2.3.4 // NOT a valid value, as sf-decimal only allows one dot Example-Header: "1.2" // sf-string Example-Header: 1.2 // sf-decimal >Of course, we could specify something like "try to parse it as a Structured >Value; if serialisation >fails, serialise it as a String." That strategy might be workable, but it >creates a lot of complexity -- >at runtime when you have to test the value by running code, and when values >are handled, because >now they could come in multiple forms. > >Always serialising as a string recognises that, from the standpoint of the >Link header field, the >value's type is opaque. In general, if a parser is not able to determine the encoding without "testing" values etc, the syntax is bad. But, in the case of structured field values that is not the case: the parser will always know if a value is sf-string, sf-integer, sf-decimal etc. Regards, Christer smime.p7s Description: S/MIME cryptographic signature ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
Hi Christer, > On 20 May 2023, at 2:58 am, Christer Holmberg > wrote: [...] >> Ah. The reason is that allowing any type would require creating a mapping of >> current values to SF types, and there >> are just too many potential (and undocumented) values already in use to do >> this. > > I don't think that is true. Just because the Parameter syntax allows values > to > be encoded sf-string, sf-token, sf-boolean etc it doesn't mean that you have > to map each value (existing or new ones) to each of those encodings. If a > value is defined as a String, then it has to be encoded as a sf-string. Consider an implementation that wants to serialise a link relation that has a 'foo' Parameter that it has no special knowledge of. If the value is "bar", that's very straightforward -- it will successfully serialise as a Token. However, consider the value "1.2.3.4" -- it will fail parsing, because it looks like an Integer or Decimal to the parser, but it isn't. Of course, we could specify something like "try to parse it as a Structured Value; if serialisation fails, serialise it as a String." That strategy might be workable, but it creates a lot of complexity -- at runtime when you have to test the value by running code, and when values are handled, because now they could come in multiple forms. Always serialising as a string recognises that, from the standpoint of the Link header field, the value's type is opaque. > Having said that, I'm fine with having the restriction, because in reality I > assume the values always will have to be encoded as sf-strings anyway (you > can't encode a URI as a sf-integer, sf-boolean etc). Ok. Cheers, -- Mark Nottingham https://www.mnot.net/ ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
Hi Mark, Q2_2: The text says "Parameter values MUST be Strings." It is unclear what "Strings" means. Does it mean that parameter values must be encoded as quoted-strings? If so, why? RFC8288 says that parameter values can be encoded both as token and quoted-string. >>> >>> S 1.1: "This specification uses the following terms from >>> [STRUCTURED-FIELDS]: List, String, Parameter." >> >> Yes. But, in Section 3.1.2 of [STRUCTURED-FIELDS] there is no >> restriction that the Parameter value must by String. My question is >> why you are making that restriction, instead of just allowing the >> different Parameter value encodings defined in [STRUCTURED-FIELDS]? > > Ah. The reason is that allowing any type would require creating a mapping of > current values to SF types, and there > are just too many potential (and undocumented) values already in use to do > this. I don't think that is true. Just because the Parameter syntax allows values to be encoded sf-string, sf-token, sf-boolean etc it doesn't mean that you have to map each value (existing or new ones) to each of those encodings. If a value is defined as a String, then it has to be encoded as a sf-string. Having said that, I'm fine with having the restriction, because in reality I assume the values always will have to be encoded as sf-strings anyway (you can't encode a URI as a sf-integer, sf-boolean etc). Thanks! Regards, Christer smime.p7s Description: S/MIME cryptographic signature ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
Hi Christer, Thanks, see responses below. > On 19 May 2023, at 1:13 pm, Christer Holmberg > wrote: > > Hi Mark, > > Please see inline. > >>> Q2_1: There is no ABNF for the header field. There are examples using >>> both quotes ("/{username}") and angle brackets >>> (), so please include the ABNF. >> >> This is a Structured Field; in the HTTP community, we've agreed that >> documenting them with ABNF is not good practice. > > Gotha. > > (I was comparing this to RFC 8288, and assumed that you still would have to > define the ABNF, following the rules of [STRUCTURED-FIELDS]) > > But, then I have the following question: > > Section 2 says: "Its value is a List of Strings. Each String is a URI > Template..." > > According to [STRUCTURED-FIELDS]), the syntax for String is: sf-string = > DQUOTE *chr DQUOTE > > From the example in Section 2, does not follow that > syntax, does it? You must use DQUOTEs. Yes, that was a transposition error that's since been corrected. >>> Q2_2: The text says "Parameter values MUST be Strings." >>> >>> It is unclear what "Strings" means. Does it mean that parameter values >>> must be encoded as quoted-strings? If so, why? RFC8288 says that >>> parameter values can be encoded both as token and quoted-string. >> >> S 1.1: "This specification uses the following terms from >> [STRUCTURED-FIELDS]: List, String, Parameter." > > Yes. But, in Section 3.1.2 of [STRUCTURED-FIELDS] there is no restriction > that > the Parameter value must by String. My question is why you are making that > restriction, instead of just allowing the different Parameter value encodings > defined in [STRUCTURED-FIELDS]? Ah. The reason is that allowing any type would require creating a mapping of current values to SF types, and there are just too many potential (and undocumented) values already in use to do this. Cheers, -- Mark Nottingham https://www.mnot.net/ ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
Hi Mark, Please see inline. >> Q2_1: There is no ABNF for the header field. There are examples using >> both quotes ("/{username}") and angle brackets >> (), so please include the ABNF. > > This is a Structured Field; in the HTTP community, we've agreed that > documenting them with ABNF is not good practice. Gotha. (I was comparing this to RFC 8288, and assumed that you still would have to define the ABNF, following the rules of [STRUCTURED-FIELDS]) But, then I have the following question: Section 2 says: "Its value is a List of Strings. Each String is a URI Template..." According to [STRUCTURED-FIELDS]), the syntax for String is: sf-string = DQUOTE *chr DQUOTE >From the example in Section 2, does not follow that syntax, does it? You must use DQUOTEs. >> Q2_2: The text says "Parameter values MUST be Strings." >> >> It is unclear what "Strings" means. Does it mean that parameter values >> must be encoded as quoted-strings? If so, why? RFC8288 says that >> parameter values can be encoded both as token and quoted-string. > > S 1.1: "This specification uses the following terms from > [STRUCTURED-FIELDS]: List, String, Parameter." Yes. But, in Section 3.1.2 of [STRUCTURED-FIELDS] there is no restriction that the Parameter value must by String. My question is why you are making that restriction, instead of just allowing the different Parameter value encodings defined in [STRUCTURED-FIELDS]? Regards, Christer smime.p7s Description: S/MIME cryptographic signature ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
Re: [Gen-art] Genart last call review of draft-ietf-httpapi-link-template-02
Hi Christer, Thanks for the review; responses below. > On 16 May 2023, at 1:37 pm, Christer Holmberg via Datatracker > wrote: [...] > Q2_1: There is no ABNF for the header field. There are examples using both > quotes ("/{username}") and angle brackets (), so > please include the ABNF. This is a Structured Field; in the HTTP community, we've agreed that documenting them with ABNF is not good practice. > Q2_2: The text says "Parameter values MUST be Strings." > > It is unclear what "Strings" means. Does it mean that parameter values must be > encoded as quoted-strings? If so, why? RFC8288 says that parameter values can > be encoded both as token and quoted-string. S 1.1: "This specification uses the following terms from [STRUCTURED-FIELDS]: List, String, Parameter." > Q2_3: The text says: > > Link-Template: ; > rel="author" anchor="#{book_id}" > > Is there a ";" missing between the rel and anchor parameters? Yes; already fixed. > Q2_4: The text says: > >Link-Template: "/widgets/{widget_id}" > rel="https://example.org/rel/widget;; > var-base="https://example.org/vars/; > > Is there a ";" missing at the end of the first line? Yes - thanks! Cheers, -- Mark Nottingham https://www.mnot.net/ ___ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art