Consider moving WebIDL to Appendix or Note #179

Closed
gkellogg opened this Issue Oct 31, 2012 · 11 comments

Comments

Projects
None yet
5 participants
Owner

gkellogg commented Oct 31, 2012

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.

Owner

msporny commented Nov 1, 2012

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

Member

lanthaler commented Nov 1, 2012

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

Owner

msporny commented Nov 7, 2012

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

Member

lanthaler commented Nov 8, 2012

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 commented Nov 8, 2012

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.

Member

lanthaler commented Nov 8, 2012

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

Owner

gkellogg commented Nov 8, 2012

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

Owner

msporny commented Nov 20, 2012

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

Contributor

tidoust commented Nov 20, 2012

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

Member

lanthaler commented Nov 20, 2012

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 lanthaler added a commit that referenced this issue Dec 4, 2012

@lanthaler lanthaler Place the Algorithms section in the JSON-LD API document before the A…
…PI section

This addresses #179.
2c7a51d
Member

lanthaler commented Dec 4, 2012

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

lanthaler closed this Dec 5, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment