Consider moving WebIDL to Appendix or Note

[gkellogg]

During the F2F, there was some concern about having the RDF WG produce an API. Turtle doesn't do this, and most other RDF specs concern themselves with defining processing rules and requirements, and not the specific API.

@msporny is of the view that the fact that other RDF specs don't have an API is why there hasn't been enough uptake of the technologies. This was also feedback given against RDFa, which resulted in attempts to defining an RDFa API (along with related APIs). Microdata has an API.

We could consider de-emphasizing the WebIDL definitions by either placing them in a normative Appendix or moving to a WG Note.

[msporny]

I'd be fine w/ a normative appendix for the WebIDL definitions.

[lanthaler]

I’d be fine with that as well. We should check with the RDF WG if that’s enough

[msporny]

Spoke with Ivan, I'm now fine with making it a non-normative section as it probably won't affect interoperability to do so.

[lanthaler]

PROPOSAL 1: Move WebIDL definitions in API spec into a normative appendix

PROPOSAL 2: Keep WebIDL definitions at the beginning of the API spec but make that section non-normative

PROPOSAL 3: Move WebIDL definitions in API spec into a non-normative appendix

[cygri]

PROPOSAL 4: Swap sections 3 (WebIDL) and 4 (Algorithms).

PROPOSAL 5: Close without change.

To be honest, I believe that renaming the document to something other than “API” will make this issue moot.

[lanthaler]

PROPOSAL 1: -0.5
PROPOSAL 2: +0.5
PROPOSAL 3: -0.5
PROPOSAL 4: -0.5
PROPOSAL 5: +1

[gkellogg]

PROPOSAL 1: +1
PROPOSAL 2: +0
PROPOSAL 3: +0
PROPOSAL 4: +1
PROPOSAL 5: +0

[msporny]

PROPOSAL 1: +0.7
PROPOSAL 2: -1
PROPOSAL 3: +0.7
PROPOSAL 4: +0.5
PROPOSAL 5: +0

[tidoust]

The structure of the spec is important but less than what its content. The key point here is whether we want to keep the API or not.

If we do and the RDF WG is not too happy about it, note we could also propose to define two classes of product: a "JSON-LD processor" that implements the algorithms and, say, a "JSON-LD API library" that exposes the API (and also implements the underlying algorithms, of course). That's a way to retain a normative API while still leaving it up to implementations to decide which class of product they implement.

The API strikes me as much more than informative only. It defines interoperability conditions for implementations willing to expose an API. Moving it to a non normative appendix sounds like attempting some Jedi trick on the standardization process: "psst, the API is there, we've just hidden it". I cannot think of any spec that defines an informative API. Is there one?

PROPOSAL 1: -1
PROPOSAL 2: -1
PROPOSAL 3: -1. Moving it to a non normative appendix bugs me, as said. I would rather see two classes of product as suggested above.
PROPOSAL 4: 0
PROPOSAL 5: +1

[lanthaler]

RESOLVED: Place the Algorithms section in the JSON-LD API document before the API section. Make the API section normative, but clarify that implementers MAY provide their own API that is compliant with the Algorithms.

[lanthaler]

I updated the spec according the resolution. Unless I hear objections, I will close this issue in 24 hours.