Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Consider moving WebIDL to Appendix or Note #179

Closed
gkellogg opened this Issue · 11 comments

5 participants

@gkellogg
Owner

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
Owner

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

@lanthaler
Owner
@msporny
Owner

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
Owner

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
Collaborator

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
Owner

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

@gkellogg
Owner

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

@msporny
Owner

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
Owner

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
Owner

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

@lanthaler lanthaler closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.