search

oauth-wg / oauth-selective-disclosure-jwt

https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/
Other
57 stars 31 forks source link

reword "for those who celebrate" referring to ABNF #461

Closed rohanmahy closed 2 months ago

rohanmahy commented 2 months ago

Now in draft -12 "As an alternative illustration of the SD-JWT format, for those who celebrate, ABNF [RFC5234] for the SD-JWT, SD-JWT+KB, and various constituent parts is provided here:"

Suggested: "For those who already have tooling using Augmented Backus Naur Form (ABNF) {{!RFC5234}}, an optional ABNF formal grammar representaton of SD-JWT, SD-JWT+KB, and various constituent parts is provided here:"

bc-pi commented 2 months ago

Will discuss with the editor team but the cited text from -12 is intentional and, in the humble opinion of its author, conveys the intent as intended. Meanwhile the suggested text changes the stated audience (some folks find ABNF useful even without tooling), uses a different reference syntax than tooling the draft source uses, and loses the satire in the original text that attempts to poke fun at the occasional absurdity of these endeavors.

danielfett commented 2 months ago

+1

rohanmahy commented 2 months ago

Grammatically, the statement as written is a non-sequitur. For those who celebrate what? You seem not to care for ABNF, which is fine, but do you celebrate your partner's birthday? Halloween? The beginning of summer? So this ABNF is for you because you celebrate! Happy World Samosa Day, here is your free ASN.1 encoding!

A specification is for its readers. Including an in-joke is only appropriate to the extent it does not confuse or distract the reader. Take 2: "An optional Augmented Backus Naur Form (ABNF) {{!RFC5234}} formal grammar representaton of SD-JWT, SD-JWT+KB, and various constituent parts is provided here:"

On a more constructive note, I can write a PR to put the ABNF in an appendix.

(This is an Issue, not a PR; you clearly understand the reference format which an editor can either adjust during incorporation or ask me to write a PR, which would have the same reference convention as the draft.)

danielfett commented 2 months ago

I think the current wording is fine as an easteregg. We can move the "for those who celebrate" part to the end of the sentence to make it easier to read.