-
Notifications
You must be signed in to change notification settings - Fork 152
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a conformance section #166
Comments
+1 to all of the above. |
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.
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 |
Nice work! A couple of comments:
|
Thanks Gregg, Ref. 1) I agree that the definition of a JSON-LD processor needs to be revisited.
If people want to insist on the JSON-LD dataset, this could be tweaked to e.g.:
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. 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. |
HTML diff between the original version and the new version: |
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. |
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. |
@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: 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. |
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. |
I think we probably still need a conformance section, just one that relates to JSON-LD documents. |
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. |
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. |
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. |
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. |
Thanks! I don't know how that's handled but isn't "should not" != "SHOULD NOT"? |
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). |
+1 looks good. |
The proposed Conformance section says:
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. |
Good point. I'll make the change. |
I just dropped that part from the definition, see: |
RESOLVED: Add a conformance section to the JSON-LD Syntax specification by merging pull request 194. |
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. |
Done: http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0014.html Unleass I hear objections, I will close this issue in 24h. |
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:
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:
The text was updated successfully, but these errors were encountered: