JSON keys are incompatible with Web IDL dictionaries

[annevk]

Per https://w3ctag.github.io/design-principles/#casing-rules an IDL dictionary member ends up as fooBar and an equivalent JSON key as foo_bar. When an API has both an imperative (IDL) and declarative (JSON) entry point, this can lead to awkward situations, as @saschanaz explains in w3c/push-api#385 (comment):

[T]he callers would have to deal with this casing in that case, like:

onpush = async (ev) => {
  // Err, our little cute browser doesn't support declarative web push,
  // so we are here for nice progressive web.
  const { notification } = await ev.data.json();
  
  // This will mostly work until you use requireInteraction.
  // await registration.showNotification(notification.title, notification);
  
  const notificationOptions = {
    ...notification,
    requireInteraction: notification.require_interaction, // 😅
  };
  await registration.showNotification(notification.title, notificationOptions);
};

I wonder it would make sense to have an exception here to prevent extra boilerplate and head-scratching?

I'm inclined to accept this inconvenience, but I wonder what other people think. We don't have that much JSON formats in the web platform so we could still change this I suspect.

Related: whatwg/infra#159.

cc @domenic @marcoscaceres @foolip

[martinthomson]

What inconvenience do you think is acceptable?

1. That web developers might need to provide "fooBar" or "foo_bar" according to the thing they are interacting with (API vs JSON), or
2. that specs might need to violate established principles about naming in {APIs|JSON}.

I'm assuming the former, but is that a violation of our priority of constituencies? Should we not favor web developers over "architectural purity"? Taking that view, either the API or the JSON should lose.

We're looking at a similar issue with structured field naming in the PPA API. There's an equivalence with the API that we want to maintain there as well, with the convention for labels in fields being "foo-bar" instead. To add to the complication, it is not permissible to use "fooBar" because labels cannot include uppercase letters and "foo-bar" is similar not valid as a label in IDL/JS.

[domenic]

I agree this is a bit annoying. I think the web has quite a few JSON formats now, so I wouldn't want to change this going forward. But maybe a carveout, like, "if your JSON format will very very often be used in tandem with a web platform API that accepts that object as an options dictionary, you can consider using the other casing rules" would be reasonable.

[annevk]

Should that rule only apply to the portions of the JSON format that will be used in such a matter, or should that then go for the entire format per some "local consistency" argument? The former would make sense if you already know that's going to be the case. The latter might end up being more consistent with formats that only later introduce such a dependency.

[domenic]

Oof, that's a tough one.

I think if it was very clear that some portion was destined for JS, then maybe making it different from the rest of the JSON document would be reasonable. Like, if it was an object in a field named api_options or something, you could have just that object use camel-casing rules, while the rest of the document uses snake_case.

But if it's less clear-cut, then consistency across the whole document feels better to me.