I originally posted this to the IETF WG email about a month ago, but I haven't heard anything back. Maybe the mail got lost in the spam filters somewhere, so I'm posting this here instead:
While implementing some parts of ARI today (based on draft 8), I noticed a bug where my test code could not parse the explanationURL field. The issue was that my client expected strict camelCase of field names and thus couldn't find the explanationURL(Url), as the latter two letters were unexpectedly capitalized.
There are several style guides out there, such as those from Google [1] or Microsoft [2] that both recommend to only capitalize the first letter on abbreviations - i.e. URL is Url in PascalCase, HTML is Html and so on. As far as I know, all parts of ACME currently follow camelCase convention, only the new ARI explanationURL is a slight divergence from that.
Would it be possible to rename the field to explanationUrl? This might make life easier for some parsers that expect full camelCase conformance.
PS: Yet another argument for the camelCase is when you consider the lower camelCase of "URL": If URL is UpperCamelCase/PascalCase, then uRL would be lower camelCase, which doesn't make much sense, right?
Why not work case insensitive? Suggest a certain style guide for human readability, but state that non-human entities such as clients MUST accept any case?
The JSON standard is case-sensitive. It is perfectly acceptable to have two distinct keys foo and FOO in the same object with differing values.
You can technically build an insensitive version of JSON on top of baseline JSON, but then you have to handle all these ambiguities, as you're introducing leniency that the base standard doesn't have. Some JSON parsers will also not natively support case-insensitive parsing, so now parsing JSON becomes needlessly hard. The library I'm using won't be able to handle that at all, as this is not an expected use case - I'm not aware of any single JSON schema that is case-insensitive.
This is a good point, and I'd be totally happy to replace explanationURL with explanationUrl. However, the document has already left the working group, gone through the RFC Editor's desk, and been assigned an RFC-to-be number. At this point, I believe it's too late to be changing anything about the wire protocol itself; it's been months since anything except for minor editorial and formatting changes have been made.
For what it's worth, I wouldn't describe capitalizing just the first letter of an acronym as "full camel case compliance". It's would be compliance with various style guides, but there is no one authoritative source of truth about what Standard Camel Case Actually Is -- even your citations are all non-authoritative style guides, and even those guides disagree on what should be done with two-letter acronyms.
My apologies that this has made your life a bit harder.
Yeah that's of course true, there's nothing that mandates that the field must be called this way. Disappointed that this got in too late (the mail must have been caught in some filter I guess, unfortunately there was no feedback from the IETF's mail server), but it is what it is.
The client-side fix is of course pretty trivial - I can just tell the parser the name of the field manually. It's just that the parser usually figures out the field names by itself, I just tell it "use camelCase specification" and then it renames the fields from Rust's snake_case to camelCase in the serializer. The explanationURL field is the only field where this doesn't work and the name must be annotated explicitly. Every parser should have such an option, so it's not a big deal.
I agree it's good to be consistent but there's an element of disconnect between why JSON exists (serializing javascript objects) and how it's actually used as a common standard for public APIs.
In practice working with json as case insensitive is the more robust strategy and if someone did produce an API with results that contained both foo and Foo fields and expected them to be treated separately, it would not survive scrutiny.