Just a quick heads up: Assuming that this is indeed a bug, we used method overloading to define the JsonLdProcessor interface in the JSON-LD specification which just went into Last Call (http://www.w3.org/TR/2013/WD-json-ld-api-20130411/#the-jsonldprocessor-interface).

There would be no other way to make the "options" parameter optional and have the callback as last parameter:

  void compact (JsonLdInput input, JsonLdContext context, JsonLdOptions options, JsonLdCallback callback);

JsonLdOptions is a dictionary

JSON-LD should be using futures there, not callbacks.

We discussed that as well but unfortunately introducing a normative dependency to the DOM spec was not acceptable at this stage.

I would consider creating broken APIs to be less acceptable than any other consideration really.

"Broken" is a quite strong word for a pattern that is well established (and has been so for years)

Markus, the normal pattern for an API that takes an options property bag is to put it last in the call signature.  Is there a reason that's not being done here?  (It would indidentally solve your overloading problem, but that's not why I'm suggesting it, fwiw.)

The reason is that we are using node-style callbacks and in node the prevalent pattern is to have the callback last. So it's basically a matter of "consistency". Switching the order of the two parameters as you suggest is the backup plan in case the WebIDL bug doesn't get fixed.

It sounds like in this instance "Node" style and "Web" style don't agree...  It's not clear to me why we're using the former for a web spec (or using webidl for a non-web spec, if this is not a web spec), honestly.

In particular, all sorts of things about dictionaries are optimized for use in web specs....

(As a note, though, the (object or object[]) pattern that spec uses is also not valid WebIDL.)

> It sounds like in this instance "Node" style and "Web" style
> don't agree...  It's not clear to me why we're using the former
> for a web spec (or using webidl for a non-web spec, if this
> is not a web spec), honestly.

Hmm... would you mind sending this comment directly to public-rdf-comments@w3.org so that it can be formally addressed? Thanks.

Why is object or object[] not valid WebIDL? The only restriction on arrays I've found in the WebIDL spec is the following: "The element type of an array MUST NOT be a sequence or dictionary type." Is it because object and object[] are not distinguishable? What could we do about that?

(In reply to comment #9)
> > It sounds like in this instance "Node" style and "Web" style
> > don't agree...  It's not clear to me why we're using the former
> > for a web spec (or using webidl for a non-web spec, if this
> > is not a web spec), honestly.
> 
> Hmm... would you mind sending this comment directly to
> public-rdf-comments@w3.org so that it can be formally addressed? Thanks.
> 
> Why is object or object[] not valid WebIDL? The only restriction on arrays
> I've found in the WebIDL spec is the following: "The element type of an
> array MUST NOT be a sequence or dictionary type." Is it because object and
> object[] are not distinguishable? What could we do about that?

You can't do anything about it.  That's the whole point of "not distinguishable" - you can't distinguish them in a reliable way.  (Node and other JS libraries often use some arbitrary form of duck-typing to accomplish this, but that doesn't work at large.)

I sent http://lists.w3.org/Archives/Public/public-rdf-comments/2013Apr/0022.html, fwiw.

For this particular bug, I do think it would be OK to distinguish between dictionaries and callbacks based on [[Call]].  Note that we can't thus distinguish between dictionaries and callback interfaces.

(In reply to comment #10)
> (In reply to comment #9)
> > Why is object or object[] not valid WebIDL? The only restriction on arrays
> > I've found in the WebIDL spec is the following: "The element type of an
> > array MUST NOT be a sequence or dictionary type." Is it because object and
> > object[] are not distinguishable? What could we do about that?
> 
> You can't do anything about it.  That's the whole point of "not
> distinguishable" - you can't distinguish them in a reliable way.  (Node and
> other JS libraries often use some arbitrary form of duck-typing to
> accomplish this, but that doesn't work at large.)

Are saying that an implementation of the API wouldn't be able to find out what has been passed? What about ECMAScript 5's isArray function?

This methods are used to transform JSON-LD documents which can be objects or arrays as at the top-level (just as JSON according RFC4627). We use the (object or object[]) union type to describe that in WebIDL. What other type should we use instead? Just object since an array is also an object? I fear that would confuse most readers.

(In reply to comment #11)
> I sent
> http://lists.w3.org/Archives/Public/public-rdf-comments/2013Apr/0022.html,
> fwiw.

Thanks.


> For this particular bug, I do think it would be OK to distinguish between
> dictionaries and callbacks based on [[Call]].

Great. I hope others agree.


> Note that we can't thus distinguish between dictionaries and callback
> interfaces.

OK.

The JSON-LD issue was resolved to not require dictionaries and callbacks to be distinguishable, so closing as WONTFIX.