Add a conformance section #166

Closed
tidoust opened this Issue Oct 18, 2012 · 24 comments

Comments

Projects
None yet
5 participants
@tidoust
Contributor

tidoust commented Oct 18, 2012

Reviewing the JSON-LD Syntax spec, I noted a few inconsistencies on the way normative statements are used. My concerns essentially boil down to "there is no conformance section" so that's the main change I suggest in the end. A conformance section is a somewhat boring one, for sure, but it is quite useful to clarify the classes of products that implement the spec. Having a conformance section is also good practice according to QA Framework: Specification Guidelines.

Unless I missed something, there are two classes of products that "implement" the JSON-LD spec: JSON-LD documents and JSON-LD processors. These classes need to be defined somewhere. In particular, there is nothing right now that describes what a JSON-LD processor does with a JSON-LD document. It processes it, sure, but what's the result of that processing?

I suggest to add a Conformance section with the following content:

Conformance

The JSON-LD Syntax specification describes the conformance criteria for JSON-LD documents (relevant to authors and authoring tool implementors) and processors (relevant to Linked Data tools implementors).

A JSON-LD document is a JSON document that expresses Linked Data in JSON. A JSON-LD Document complies with this specification if it follows the normative statements for documents defined in Appendix A. JSON-LD Grammar. For convenience, normative statements for documents are often phrased as statements on the properties of the document.

A JSON-LD processor parses a JSON-LD document and generates the corresponding JSON-LD Graph (mapping terms to IRIs and coercing values). A JSON-LD processor complies with this specification if it follows the normative statements for processors. Statements that are applicable to a JSON-LD Processor are identified in this document by use of the term "JSON-LD processor" in the singular or plural.

The key words must, must not, required, shall, shall not, should, should not, recommended, not recommended, may, and optional in this Recommendation have the meaning defined in [RFC 2119].

Ideally, that section would appear close to the top but after the other terms have been defined. That typically means right after section 3.3, although the conformance section should not be a sub heading of "Basic Concepts".

Related updates and questions:

  • There is no normative reference to RFC2119, there should be one
  • I explicitly mentioned Appendix A for normative statements that apply to JSON-LD documents. Am I right to assert that this section contains all the normative statements.
  • The spec should not contain normative statements that do not apply to any of the classes of products mentioned in the conformance section. In particular, I don't understand the use of normative key words in the JSON-LD data model section because the impact on JSON-LD documents and processors is indirect, at best. I would simply drop the use of normative keywords (they are not needed, the section defines concepts). The should constraints that affect JSON-LD Documents are already addressed by statements in the JSON-LD Grammar, AFAICT.
  • Normative statements may benefit from a bit of rewrite to clarify the class of product they apply to. I'd be happy to go through the spec and propose concrete updates (typically in the form of a pull request), but I'd like some feedback on the above first.
@cygri

This comment has been minimized.

Show comment Hide comment
@cygri

cygri Oct 22, 2012

+1 to all of the above.

cygri commented Oct 22, 2012

+1 to all of the above.

tidoust pushed a commit to tidoust/json-ld.org that referenced this issue Nov 5, 2012

François Daoust
Add Conformance section as proposed in #166.
The JSON-LD Data Model is now in a proper section, followed by
a terminology section with general terminology and keywords. The
Conformance section (that refers to the notion of JSON-LD graph
defined in the JSON-LD Data Model section) appears next.

No further changes in this commit.
@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 5, 2012

Contributor

See annoucement for proposed "bit of rewrite" on the JSON-LD mailing-list http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0001.html

Contributor

tidoust commented Nov 5, 2012

See annoucement for proposed "bit of rewrite" on the JSON-LD mailing-list http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0001.html

@gkellogg

This comment has been minimized.

Show comment Hide comment
@gkellogg

gkellogg Nov 6, 2012

Owner

Nice work! A couple of comments:

  1. In the third paragraph of Conformance, the text indicates that a processor creates a JSON-LD graph; it's really creating a JSON-LD dataset, which typically just includes a single (default) graph. We need to be sure we're consistent when talking about graphs and/or datasets.

  2. Also, in Conformance, you reference normative statements in Basic Concepts and Advanced Concepts, although you indicated in your summary that those sections no longer include normative statements. In fact, there are some MUSTs in those sections (that are for documents, not processors).

7.4) ... an author must specify an IRI to a valid JSON-LD document in an HTTP Link Header
7.4) ... The referenced document must have a top-level node definition
7.4) ... JSON-LD documents served with the application/ld+json media type must have all context information, including references to external contexts, within the body of the document.
7.9) (not really from your edit), a Note contains : ... The use of @container in the body of a JSON-LD document, i.e., outside @context must be ignored by JSON-LD processors. We should remove normative statements from notes.

  1. Your comments indicated moving examples out of Appendix A, but there are still some there.
Owner

gkellogg commented Nov 6, 2012

Nice work! A couple of comments:

  1. In the third paragraph of Conformance, the text indicates that a processor creates a JSON-LD graph; it's really creating a JSON-LD dataset, which typically just includes a single (default) graph. We need to be sure we're consistent when talking about graphs and/or datasets.

  2. Also, in Conformance, you reference normative statements in Basic Concepts and Advanced Concepts, although you indicated in your summary that those sections no longer include normative statements. In fact, there are some MUSTs in those sections (that are for documents, not processors).

7.4) ... an author must specify an IRI to a valid JSON-LD document in an HTTP Link Header
7.4) ... The referenced document must have a top-level node definition
7.4) ... JSON-LD documents served with the application/ld+json media type must have all context information, including references to external contexts, within the body of the document.
7.9) (not really from your edit), a Note contains : ... The use of @container in the body of a JSON-LD document, i.e., outside @context must be ignored by JSON-LD processors. We should remove normative statements from notes.

  1. Your comments indicated moving examples out of Appendix A, but there are still some there.
@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 6, 2012

Contributor

Thanks Gregg,

Ref. 1) I agree that the definition of a JSON-LD processor needs to be revisited.
I note the term "dataset" is not used anywhere in the JSON-LD syntax document for the time being.
On top of this, I would really mention the JSON-LD API here:

A JSON-LD processor parses and transforms a JSON-LD document according to the algorithms defined in [JSON-LD API] and exposes the results of these transformations using the API defined in that document [JSON-LD API].

If people want to insist on the JSON-LD dataset, this could be tweaked to e.g.:

A JSON-LD processor parses a JSON-LD document to create a JSON-LD dataset according to the expansion algorithm defined in [JSON-LD API]. It exposes the API defined in [JSON-LD API] to transform the JSON-LD dataset following the algorithms defined in that document."

My main point is that there should be a strong tie between the JSON-LD syntax document and the JSON-LD API as the algorithms formalize the principles described in the JSON-LD syntax document. Actually, up until this edit, the JSON-LD API was an "informative" reference. I made it a "normative" reference. That effectively means both documents must progress towards Recommendation at the same pace but I don't see how this could be avoided.

Ref. 2), Yes, I forgot to update the conformance section after all updates.
I noted in my email that the "Referencing Contexts from JSON Documents" was the only one still containing normative statements on JSON-LD documents. I don't think this would fit in the grammar, but we could perhaps move the section to its own high-level section in the document.
Also note I left most normative statements that apply to JSON-LD processors pending discussion on 1)

Ref 3) I mention moving examples out of Appendix A as "not done yet". I believe the group agreed to move them away and I think that's a good idea. I just didn't want to make too many updates at once.

Contributor

tidoust commented Nov 6, 2012

Thanks Gregg,

Ref. 1) I agree that the definition of a JSON-LD processor needs to be revisited.
I note the term "dataset" is not used anywhere in the JSON-LD syntax document for the time being.
On top of this, I would really mention the JSON-LD API here:

A JSON-LD processor parses and transforms a JSON-LD document according to the algorithms defined in [JSON-LD API] and exposes the results of these transformations using the API defined in that document [JSON-LD API].

If people want to insist on the JSON-LD dataset, this could be tweaked to e.g.:

A JSON-LD processor parses a JSON-LD document to create a JSON-LD dataset according to the expansion algorithm defined in [JSON-LD API]. It exposes the API defined in [JSON-LD API] to transform the JSON-LD dataset following the algorithms defined in that document."

My main point is that there should be a strong tie between the JSON-LD syntax document and the JSON-LD API as the algorithms formalize the principles described in the JSON-LD syntax document. Actually, up until this edit, the JSON-LD API was an "informative" reference. I made it a "normative" reference. That effectively means both documents must progress towards Recommendation at the same pace but I don't see how this could be avoided.

Ref. 2), Yes, I forgot to update the conformance section after all updates.
I noted in my email that the "Referencing Contexts from JSON Documents" was the only one still containing normative statements on JSON-LD documents. I don't think this would fit in the grammar, but we could perhaps move the section to its own high-level section in the document.
Also note I left most normative statements that apply to JSON-LD processors pending discussion on 1)

Ref 3) I mention moving examples out of Appendix A as "not done yet". I believe the group agreed to move them away and I think that's a good idea. I just didn't want to make too many updates at once.

@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 6, 2012

Contributor

HTML diff between the original version and the new version:
http://goo.gl/bUZPM
(that loses ReSpec a bit, but is still readable)

Contributor

tidoust commented Nov 6, 2012

HTML diff between the original version and the new version:
http://goo.gl/bUZPM
(that loses ReSpec a bit, but is still readable)

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 6, 2012

Member

Great work François!

I started to comment directly on your commits but figured that wouldn't be the best idea to give feedback. You made quite a few changes and I’m OK with most of them. One of the few that I don’t like is for example the fact that you completely removed the sentence discouraging the use of empty terms or term that begin with an @ from the context section and move that into the grammar section. I’m also not sure if lowercasing all RFC2119 keywords is a really a good idea? @gkellogg @msporny thoughts?

What would be the best way to proceed? Should I start merging in the uncontroversial changes.

Member

lanthaler commented Nov 6, 2012

Great work François!

I started to comment directly on your commits but figured that wouldn't be the best idea to give feedback. You made quite a few changes and I’m OK with most of them. One of the few that I don’t like is for example the fact that you completely removed the sentence discouraging the use of empty terms or term that begin with an @ from the context section and move that into the grammar section. I’m also not sure if lowercasing all RFC2119 keywords is a really a good idea? @gkellogg @msporny thoughts?

What would be the best way to proceed? Should I start merging in the uncontroversial changes.

@gkellogg

This comment has been minimized.

Show comment Hide comment
@gkellogg

gkellogg Nov 6, 2012

Owner

BTW, regarding document diffs. I think the newest versions of ReSpec fix the issue, however, we have to have a previousDiffURI pointing to someplace that will actually come up; probably in the json-ld.org/spec/ED space. Using the keyboard shortcut to bring this up is really useful.

Owner

gkellogg commented Nov 6, 2012

BTW, regarding document diffs. I think the newest versions of ReSpec fix the issue, however, we have to have a previousDiffURI pointing to someplace that will actually come up; probably in the json-ld.org/spec/ED space. Using the keyboard shortcut to bring this up is really useful.

@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 7, 2012

Contributor

@lanthaler, I updated my local copy of the spec to incorporate your feedback. I created a proper issue for the definition of a JSON-LD processor, referenced from the Conformance section:
tidoust/json-ld.org@0cabdac

It's certainly not a good idea to use RFC2119 keywords without meaning to use RFC2119, but it's also relatively benign for "may" so I sticked to that in the interest of time and of reducing the number of changes I proposed to the spec. Feel free to use other words...

Ref. integration, if you're fine with most of these edits, a pull request followed by a few fixes on your side might be the easiest way forward. I'm also happy to integrate further feedback before sending in the pull request. If you prefer to incorporate the changes one by one yourself, well, that sounds like more work but, hey, that's your call ;) Just let me know.

Contributor

tidoust commented Nov 7, 2012

@lanthaler, I updated my local copy of the spec to incorporate your feedback. I created a proper issue for the definition of a JSON-LD processor, referenced from the Conformance section:
tidoust/json-ld.org@0cabdac

It's certainly not a good idea to use RFC2119 keywords without meaning to use RFC2119, but it's also relatively benign for "may" so I sticked to that in the interest of time and of reducing the number of changes I proposed to the spec. Feel free to use other words...

Ref. integration, if you're fine with most of these edits, a pull request followed by a few fixes on your side might be the easiest way forward. I'm also happy to integrate further feedback before sending in the pull request. If you prefer to incorporate the changes one by one yourself, well, that sounds like more work but, hey, that's your call ;) Just let me know.

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 7, 2012

Member

PROPOSAL 1: Remove all statements concerning a JSON-LD processor from @tidoust's conformance section and merge the rest into the JSON-LD syntax spec.

Member

lanthaler commented Nov 7, 2012

PROPOSAL 1: Remove all statements concerning a JSON-LD processor from @tidoust's conformance section and merge the rest into the JSON-LD syntax spec.

@gkellogg

This comment has been minimized.

Show comment Hide comment
@gkellogg

gkellogg Nov 7, 2012

Owner

I think we probably still need a conformance section, just one that relates to JSON-LD documents.

Owner

gkellogg commented Nov 7, 2012

I think we probably still need a conformance section, just one that relates to JSON-LD documents.

@msporny

This comment has been minimized.

Show comment Hide comment
@msporny

msporny Nov 7, 2012

Owner

PROPOSAL 1: -1

PROPOSAL 2: Move all statements concerning a "conforming JSON-LD Processor" to the JSON-LD API document, normatively define a "conforming JSON-LD Document" in the Conformance section.

Owner

msporny commented Nov 7, 2012

PROPOSAL 1: -1

PROPOSAL 2: Move all statements concerning a "conforming JSON-LD Processor" to the JSON-LD API document, normatively define a "conforming JSON-LD Document" in the Conformance section.

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 7, 2012

Member

OK, maybe that wasn't clear enough because I still had the proposals I wrote for issue #184 in my mind and was consequently just talking about the syntax spec in this issue. The proposal is effectively the same as what @msporny wrote just split between this and issue #184.

Member

lanthaler commented Nov 7, 2012

OK, maybe that wasn't clear enough because I still had the proposals I wrote for issue #184 in my mind and was consequently just talking about the syntax spec in this issue. The proposal is effectively the same as what @msporny wrote just split between this and issue #184.

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 7, 2012

Member

Thanks François! Could you please also re-add the statement that terms starting with an @ should not be used in the context section?

Btw., do you know that you can add commits to a PR until it is closed? So please file the pull request so that we can discuss it directly.

Member

lanthaler commented Nov 7, 2012

Thanks François! Could you please also re-add the statement that terms starting with an @ should not be used in the context section?

Btw., do you know that you can add commits to a PR until it is closed? So please file the pull request so that we can discuss it directly.

@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 7, 2012

Contributor

I re-added the statement, but note the wording is a bit awkward as it really needs to say "should not" without saying "should not"...

I actually didn't know one could add commits to a pull request after it was created. Nice. I just filed it.

Contributor

tidoust commented Nov 7, 2012

I re-added the statement, but note the wording is a bit awkward as it really needs to say "should not" without saying "should not"...

I actually didn't know one could add commits to a pull request after it was created. Nice. I just filed it.

@cygri

This comment has been minimized.

Show comment Hide comment
@cygri

cygri Nov 7, 2012

Throwing this bit from #188 in here, stated a bit clearer:

I have the impression that “JSON-LD Syntax” could be treated as a more Primer/Tutorial-style document, and all the normative “meat” (data model, grammar/well-formedness definitions, algorithms, APIs, conformance) moved to the “Processing” spec. That would free the Primer spec from having to spell out everything in complete detail, and allows a focus on accuracy, clarity, completeness and correctness in the Processing spec. It would also resolve the problem with potential circular normative references, and readers of the Processing spec don't have to jump back and forth between documents to figure out all the details.

cygri commented Nov 7, 2012

Throwing this bit from #188 in here, stated a bit clearer:

I have the impression that “JSON-LD Syntax” could be treated as a more Primer/Tutorial-style document, and all the normative “meat” (data model, grammar/well-formedness definitions, algorithms, APIs, conformance) moved to the “Processing” spec. That would free the Primer spec from having to spell out everything in complete detail, and allows a focus on accuracy, clarity, completeness and correctness in the Processing spec. It would also resolve the problem with potential circular normative references, and readers of the Processing spec don't have to jump back and forth between documents to figure out all the details.

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 8, 2012

Member

I re-added the statement, but note the wording is a bit awkward as it really needs to say "should not" without saying "should not"...

Thanks! I don't know how that's handled but isn't "should not" != "SHOULD NOT"?

Member

lanthaler commented Nov 8, 2012

I re-added the statement, but note the wording is a bit awkward as it really needs to say "should not" without saying "should not"...

Thanks! I don't know how that's handled but isn't "should not" != "SHOULD NOT"?

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 9, 2012

Member

I think François pull request (PR194) is now ready to be merged. You can find the diff here.

PROPOSAL 3: Merge PR194 without further changes (this will not automatically close this issue).

Member

lanthaler commented Nov 9, 2012

I think François pull request (PR194) is now ready to be merged. You can find the diff here.

PROPOSAL 3: Merge PR194 without further changes (this will not automatically close this issue).

@gkellogg

This comment has been minimized.

Show comment Hide comment
@gkellogg

gkellogg Nov 9, 2012

Owner

+1 looks good.

Owner

gkellogg commented Nov 9, 2012

+1 looks good.

@cygri

This comment has been minimized.

Show comment Hide comment
@cygri

cygri Nov 13, 2012

The proposed Conformance section says:

A JSON-LD document is a JSON document that expresses Linked Data in JSON.

This should be removed, as Linked Data is not normatively defined, and it's not relevant to conformance. It should simply say that a JSON-LD document is a JSON document that complies with the various conformance statements.

Otherwise, no objections to merging the patch.

cygri commented Nov 13, 2012

The proposed Conformance section says:

A JSON-LD document is a JSON document that expresses Linked Data in JSON.

This should be removed, as Linked Data is not normatively defined, and it's not relevant to conformance. It should simply say that a JSON-LD document is a JSON document that complies with the various conformance statements.

Otherwise, no objections to merging the patch.

@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 13, 2012

Contributor

Good point. I'll make the change.

Contributor

tidoust commented Nov 13, 2012

Good point. I'll make the change.

@tidoust

This comment has been minimized.

Show comment Hide comment
@tidoust

tidoust Nov 13, 2012

Contributor

I just dropped that part from the definition, see:
tidoust/json-ld.org@32794ee

Contributor

tidoust commented Nov 13, 2012

I just dropped that part from the definition, see:
tidoust/json-ld.org@32794ee

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 13, 2012

Member

RESOLVED: Add a conformance section to the JSON-LD Syntax specification by merging pull request 194.

Member

lanthaler commented Nov 13, 2012

RESOLVED: Add a conformance section to the JSON-LD Syntax specification by merging pull request 194.

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 13, 2012

Member

As agreed on today's telecon I merged PR 194 and will send an e-mail to the mailing list announcing the intent to close this issue in a few minutes.

Member

lanthaler commented Nov 13, 2012

As agreed on today's telecon I merged PR 194 and will send an e-mail to the mailing list announcing the intent to close this issue in a few minutes.

@lanthaler

This comment has been minimized.

Show comment Hide comment
@lanthaler

lanthaler Nov 13, 2012

Member

Done: http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0014.html

Unleass I hear objections, I will close this issue in 24h.

Member

lanthaler commented Nov 13, 2012

Done: http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0014.html

Unleass I hear objections, I will close this issue in 24h.

@lanthaler lanthaler closed this Nov 14, 2012

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