Syntax doc edits to avoid implying that JSON-LD is not RDF #288
Conversation
Attached are the corresponding changes that I see that are needed in the syntax document: http://json-ld.org/spec/latest/json-ld/ Other editorial issues that I noticed but I did not fix in the attached version: 1. The Abstract begins: "JSON is a useful data serialization and messaging format". Delete "useful" or perhaps delete the whole sentence. (Other data serialization and messaging formats are *not* useful?) 2. The Features at Risk section needs to be updated regarding blank nodes as predicates.
| <tref title="property">properties</tref> when converting to RDF, there are | ||
| three potential approaches (in order of preference):</p> | ||
| <tref title="property">properties</tref> when deserializing to RDF, | ||
| three potential approaches are suggested (in descending order of preference):</p> |
There was a problem hiding this comment.
I would prefer to drop "(in descending order of preference)" as otherwise we have to explain why as well. Furthermore, it really depends on the use case.
Taking into consideration the discussion in json-ld#287.
| </ol> | ||
| <li>If the developer wishes to use <tref title="blank node">blank nodes</tref> | ||
| as <tref title="property">properties</tref> and also wishes to interpret the | ||
| data as a (non-standard) |
There was a problem hiding this comment.
@gkellogg @dbooth-boston: So, what do we do about this (non-standard)? Just as Gregg, I would still prefer to remove it because I think it confuses more than it helps.
There was a problem hiding this comment.
I think we should remove (non-standard) from here, as we already said generalized. The Syntax doc is a better place to talk about the difference between regular- and generalized-triples/graphs/datasets to the extent that a reference to rdf11-concepts doesn't handle it.
There was a problem hiding this comment.
I think it is important to mention anywhere "generalized RDF" is mentioned, because many readers are unlikely to know that "generalized RDF" means RDF that is not standards compliant. It is fine if someone knowingly chooses to generate non-standard RDF, but it is important that they do so knowingly. Markus, what confusion do you think that clarification adds? And would it be less confusing to phrase it something like ". . . also wishes to interpret the data as generalized RDF (i.e., as RDF that is not standards compliant)"? Gregg, this is the Syntax doc we're discussing, isn't it?
There was a problem hiding this comment.
Perhaps generalized RDF can be an external definition linking to the appropriate section on rdf11-concepts. I'd rather not muddy up every reference to generalized RDF with an explanation that it is non-standard; this can be done in one place in the Syntax document when it's introduced and/or defined.
There was a problem hiding this comment.
Correction: I don't think it is necessary to warn the reader about non-standard RDF every time "generalized RDF" is mentioned. But I do think it is important to prominently warn the reader once in each document, where the "produce generalized RDF" option is discussed.
In the API document the most logical place for such a warning would be in the first paragraph of section 10.1: http://json-ld.org/spec/latest/json-ld-api/index.html#convert-to-rdf-algorithm . In the Syntax spec, if the three suggested work-arounds for blank node properties are discussed (where it says: "For authors and developers working with blank nodes as properties when deserializing to RDF . . . "), then I think that would be the most logical and important place for such a warning, since that is where the use of the "produce generalized RDF" option is suggested. (That is the location that this thread is currently discussing.) I think those two warnings would be enough -- once per document.
The point of such a warning is to alert readers who may not otherwise realize that they would be generating non-standard RDF, because it is not at all obvious from the term itself that "generalized RDF" means non-standard RDF. (If the RDF WG had called it "extended RDF" then it would have been more evident.) Such a warning will help to ensure that users who make the choice to use non-standard RDF are doing so knowingly. In fact, it would probably be helpful to include a highlighted warning box, explaining that "generalized RDF" is not standards compliant.
There was a problem hiding this comment.
+1 to "Note that generalized RDF is an extension of RDF; it does not conform to the RDF standard."
There was a problem hiding this comment.
It sounds like you are suggesting something like this:
<li>If the developer wishes to use
<tref title="blank node">blank nodes</tref> as
<tref title="property">properties</tref> and also wishes to interpret the
data as a
<tref href="http://www.w3.org/TR/rdf11-concepts/#fn-generalized-rdf-dataset">generalized RDF Dataset</tref>,
there is an option, <i>produce generalized RDF</i>,
in the [[JSON-LD-API]] to do so. Note that
<tref href="http://www.w3.org/TR/rdf11-concepts/#fn-generalized-rdf">generalized RDF</tref>
is an extension of RDF: it does not conform to the RDF standard.</li>
I think that would be adequate.
There was a problem hiding this comment.
@dbooth-boston, yes, that sounds fine to me. +1
There was a problem hiding this comment.
+1 for me as well. I’ll update the pull request in a couple of hours unless someone objects in the meantime.
There was a problem hiding this comment.
OK, I’ve made the changes in e392bb1. Does anything else need to be changed before we merge these changes?
|
@dbooth-boston @dlongley @msporny @gkellogg I've made the changes in e392bb1. Is there anything else that needs to be changed before I merge this PR? |
|
Looks ok to me. |
Syntax doc edits to avoid implying that JSON-LD is not RDF
_By David Booth:_
Attached are the corresponding changes that I see that are needed in the syntax document:
http://json-ld.org/spec/latest/json-ld/
Other editorial issues that I noticed but I did not fix in the attached version: