Re: partial comments on JSON-LD document

On Mon, Oct 22, 2012 at 12:04 AM, Manu Sporny <msporny@digitalbazaar.com> wrote:
> On 10/21/2012 04:47 AM, Richard Cyganiak wrote:
>> By the way: Using RFC2119 keywords in Notes is nonsensical. The role
>>  of a Note is to provide non-normative explanations within a
>> normative section. Putting conformance statements into a Note is
>> fundamentally wrong.
>
> As Gregg stated, we'll pull the offending text out into the main body of
> the spec.
>
>> Or perhaps MUST in JSON-LD doesn't mean the same as MUST in other W3C
>> specifications?
>
> It means exactly the same thing as it does in other W3C specs.
>
>> We will never know, since there is no Conformance section.
>
> Are you requesting a conformance section?
>
> This makes sense for language like TURTLE, but not as much for JSON-LD
> since all conforming JSON documents are conforming JSON-LD documents.
> JSON-LD provides a way of interpreting JSON if one wants to use it as
> Linked Data or wants to convert it to and from RDF. So, while you can do
> anything you can do with JSON in JSON-LD, not all of it will survive
> JSON-LD Compaction/Expansion/Flattening or conversion to RDF. This is by
> design as we don't want to make it impossible to transform the majority
> of the existing JSON documents over to JSON-LD.

Whether we call it "conforming", "valid", or something else, it sounds
a good idea to distinguish between JSON documents that use JSON-LD
keywords in the way indicated in the JSON-LD spec and those that do
not. For instance, I may use @vocab, supposed to be a IRI, as a
regular JSON property as in:
 {
   "@vocab": {
     "hello": "world"
    }
  }
... which doesn't mean anything in JSON-LD. Calling this a "conforming
JSON-LD document" does not really serve any useful purpose. That
doesn't mean that there cannot be a rule for JSON-LD processors that
ask them to ignore such constructs and proceed with the rest of the
document to ensure that they can process any kind of JSON document.

Identifying conformance criteria is a very good way to clarify how to
implement, use, and test the spec.

>
> So, if you want a conformance section (which might not be a terrible
> idea), what would you expect to see in it? I think we might start with
> something like this:
>
> """
> Conformance
> -----------
>
> JSON-LD outlines a set of rules that are used to interpret JSON
> documents as Linked Data and transform those documents to and from RDF.
> Thus, any conforming JSON document is a conforming JSON-LD document.
>
> JSON-LD conformance checkers MAY warn authors about JSON markup that
> will not survive the interpretation process, such as the use of JSON
> keys that do not have a mapping in the JSON-LD Context.
> """

See above. I believe it would be good to identify JSON documents that
explicitly follow the additional constraints set forth in the spec,
typically the "Grammar" section. That serves as a guide to authors who
want to add these precious annotations and allows to define a
validation mechanism.

The conformance section should not use normative key words such as
"MAY" either, since by definition that section should define the
classes of products that the statements apply to. Your proposed text
introduces the notion of "JSON-LD conformance checker", that's one
such class. I believe there should be a real (as in: not all documents
are conforming) "conforming JSON-LD document" class.

I created ISSUE-166 last week, initially for other reasons. I should
not have created the issue directly on github, it seems to have gone
unnoticed. I proposed some text in that issue for a possible
conformance section:
[[
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].
]]
https://github.com/json-ld/json-ld.org/issues/166

The good parts of being explicit about classes of products in a
conformance is that one can then focus on the normative statements in
the spec and associate them with classes of product with a view to
removing useless or inapplicable statements.

Francois.


> -- manu
>
> --
> Manu Sporny (skype: msporny, twitter: manusporny)
> Founder/CEO - Digital Bazaar, Inc.
> blog: The Problem with RDF and Nuclear Power
> http://manu.sporny.org/2012/nuclear-rdf/
>

Received on Monday, 22 October 2012 09:42:13 UTC