A non-optional dictionary argument makes sense at times.

[alvestrand]

See w3c/mediacapture-main#366

There are times where omitting a dictionary SHOULD result in a TypeError, even when the dictionary has no mandatory members. In mediacapture's case, the (prose) spec says that TypeError will be thrown from the procedure when you omit all the members.

In this particular case, it doesn't make sense to specify the dictionary as an optional argument, but the current spec forces us to. This is a WebIDL spec "developer gotcha" - not a Good Thing.

[bzbarsky]

This was a conscious design decision. The idea was that in general when using a dictionary in trailing position (i.e. as an options object), omitting it and passing empty object should have equivalent behavior. Since the default argument behavior is to not be optional, if we didn't have this spec requirement people would be commonly writing specs which had required option object arguments. And most option objects don't have the complicated "must provide at least one of these properties" behavior mediacapture does.

So the decision was made to nudge people in the right direction in the simple cases. The complicated cases get the behavior they want for free anyway, because they have to consider the case of {} getting passed and the behavior of not passing the argument is exactly the same as passing {}. So they don't even have to write extra prose to get the effect they want.

[alvestrand]

My complaint is the implicit statement made:

apiFunction(dictionaryType? argument)

states "You can omit the argument". Then prose will later say "you have to include the argument, and it has to be non-empty".

In this case, the behavior on missing argument and the behavior on empty argument is intended to be the same: TypeError - "you can't use this here".

If the WebIDL rule had been "CONVENTION: if an empty argument won't cause a TypeError, the argument MUST be marked Optional, to inform the user that an empty argument and an omitted argument has the same result", I would have no problem with it at all.

But that extra, misleading question mark bothers me.

[bzbarsky]

"CONVENTION: if an empty argument won't cause a TypeError, the argument MUST be marked Optional, to inform the user that an empty argument and an omitted argument has the same result"

The IDL layer has no way to tell whether an empty argument will cause a TypeError. How would this convention actually be enforced in practice?

But more to the point, for dictionaries the idea is that an empty argument and an omitted argument always has the same result. This doesn't depend on whether the empty argument causes a TypeError or not.

I assume you meant optional whenever you wrote ?.

[alvestrand]

@bzbarsky yes, I meant "optional", not "nullable". Sorry about that.
My opinion: The difference between a convention and a rule is that enforcement of the convention can be done by humans, while rules should be enforced by machinery (and therefore need to be written in ways that allow machinery to enforce them).

[bzbarsky]

Right, the whole point is that we did not expect humans to be any good at enforcing the optionality of trailing dictionaries (and in fact had seen them fail to do so repeatedly), which is why we made it a rule and not a convention.

[alvestrand]

OK, the point has been raised, and I think we've shown that there's no consensus for change. Closing.

[ayg]

So DOM has

  void observe(Node target, MutationObserverInit options);

which is invalid per this. It looks like Edge and Chrome implemented it per spec, and Firefox ignores the spec and makes it optional. This does not suggest to me that this way of encouraging good spec-writing practices is particularly effective, insofar as one of our largest and best-maintained specs just ignores it, and the one implementation that had the opportunity to notice (Gecko's WebIDL parser enforces validity) silently changed the IDL to make the warning go away. DOM has had this IDL line since at least 2012 and presumably forever, and Gecko made it optional also since 2012.

So while I don't argue with the goals of this restriction, I don't know if it's actually doing enough to warrant the confusingness of having a spec's IDL call something "optional" when really it's not. Where are these validity requirements expected to be enforced such that spec writers will notice or care?

[foolip]

@annevk

The spec has "If none of options’ childList, attributes, and characterData is true, throw a TypeError" which is hit for observe(target, {}) and would as well if the argument were allowed to be omitted. Loosening the IDL to allow things that always throw a TypeError doesn't seem very useful.

How to weigh this against spec authors that make dictionaries required when passing {} actually does something useful I don't know.

[bzbarsky]

silently changed the IDL to make the warning go away

That should not have happened; it's totally my fault as the reviewer of that patch that it did.

The good news is that this happened 4 years ago, as you note (when we initially converted MutationObserver to use WebIDL at all); I believe our IDL reviews have gotten a lot better since then.

Note that you've found one case where something slipped through the cracks, but if I recall correctly we've had multiple cases where we caught specs messing this up and got them fixed...

Loosening the IDL to allow things that always throw a TypeError doesn't seem very useful.

Just so we're clear: this is a really weird dictionary. It has all sorts of interdependency requirements on its members that can't be expressed declaratively in the IDL and hence have to be expressed in prose.

All IDL can enforce for a dictionary like this, and tries to, is that behavior is identical for passing undefined and passing {} (as long as there are no getters on Object.prototype, of course).

[bzbarsky]

Oh, and given that it's not clear to me what "Firefox ignores the spec and makes it optional" means in practice, if passing undefined just ends up throwing a TypeError anyway. That is, in this case the observable behavior is the same whether the dictionary is "optional" or not, if non-optional trailing dictionaries are supported...

[annevk]

Happy to change DOM.

I thought I filed a bug against IDL for this at some point, but all I could find that was a close match was https://www.w3.org/Bugs/Public/show_bug.cgi?id=23604 filed by bz.

[ayg]

@bzbarsky Well, it means that MutationObserver.prototype.observe.length is 2 instead of 1, which fails a wpt test and is how I noticed in the first place. I do not think this has big implications for web compat, though. :)

If Anne is happy to change DOM, then I don't have any objection to closing this and leaving WebIDL as it is, although I think it's slightly sad that the IDL will be slightly more confusing. If a confusing "optional" in an IDL were the worst problem with the web platform, we'd be in great shape. ;)