Conformance section and grammar updates #194

Merged
merged 12 commits into from Nov 13, 2012

Conversation

Projects
None yet
2 participants
Contributor

tidoust commented Nov 7, 2012

  • Conformance section added as proposed in #166.
  • Normative statements in Terminology, Basic Concepts and Advanced Concepts sections moved to the grammar (except those in "Referencing an external context from a JSON-LD document") or dropped if they were already there.
  • Grammar re-written in a more consistent way. Reader may now follow grammar constructs without being taken back to the terminology section.
  • Several typos.

François Daoust added some commits Oct 27, 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.
9a11a46
François Daoust Merge branch 'master' of https://github.com/json-ld/json-ld.org 0901a1c
François Daoust Merge branch 'master' of https://github.com/json-ld/json-ld.org f474d3a
François Daoust New "stand-alone" Grammar section
Main changes:
- Clarified that JSON terms are directly imported from the JSON spec,
and not re-defined in JSON-LD.
- Moved the definitions of "node definition", "node reference" and
"term" to the grammar. They are JSON-LD constructs.
- Introduced new grammar constructs when needed, in particular
"expanded typed value" and "expanded lanugage-tagged string"
- Re-wrote the grammar in a more consistent way to use the same
vocabulary throughout.
- Fixed grammar when needed (for instance the value in a language
map could be a language-tagged string, which seemed a typo).

Not done yet:
- All normative statements in "Basic Concepts" and "Advanced Concepts"
should be removed (provided they appear in the grammar that is!)
- There remains a couple of places where the grammar is not perfect
(@graph and apparent contradiction in expanded term definition in
particular)
- Examples in the grammar should be moved to previous sections.
- There may be a few places in "Basic Concepts" and "Advanced Concepts"
sections that would benefit from linking to the grammar.
- Some definitions may benefit from a bit of wordsmithing. For instance,
there could be a note around the definition of an IRI that explains
that, whenever the grammar says a value must be an IRI, it is taken
to mean "a string with the lexical form of an IRI".
86227bb
François Daoust Dropped normative statement from "Basic" and "Advanced" sections.
Grammar completed as necessary when the normative statements were
not captured yet (e.g. the constraint on circular dependencies
for terms definitions in a context).

Also: IRI definition modified to say that an IRI may either be
represented as an absolute IRI or a relative IRI. "terms" and
"compact IRIs" were also in the list previously, but they generate
IRIs through expansion, and the grammar makes the distinction
when it says that a value can be an IRI, a compact IRI or a term.

Normative statements on JSON-LD processors still appear in the
doc, but should probably be removed.

Also note the "Referencing Contexts from JSON Documents" section
retains its normative wording.

I also updated plural references to terms to include the "s" to
ensure the whole world gets turned into a link.
ed29483

"as if the key was not defined" -> "as if the key-value pair was not defined" would probably make it even clearer

Shouldn't we move this to the API spec?

François Daoust added some commits Nov 7, 2012

François Daoust Markus feedback on recent Conformance/Grammar updates incorporated.
- Created issue #184 to discuss the definition of a JSON-LD
processor. The doc references that issue in the meantime.
- Incorporated Markus feedback to clarify when a JSON object with
a null value is ignored
- Re-introduced statement that discourages the use of empty terms
in "Context" section. I left it in the grammar as well because that
also seems the right place to mention it but, technically speaking,
it could be removed from there since it's not a normative binding.
0cabdac
François Daoust Merge branch 'master' of https://github.com/json-ld/json-ld.org into …
…gh-pages
e804ce8
François Daoust Re-introduced sentence to discourage use of terms starting with an "@"
The grammar contains a "SHOULD NOT" statement on that. I re-introduced
a similar statement using "are to be avoided" not to duplicate the
normative statement.
dbe2f12
François Daoust Merge branch 'master' of https://github.com/json-ld/json-ld.org 3c19bfa
Member

lanthaler commented Nov 8, 2012

Could you please completely remove the parts talking about a JSON-LD processor part from the conformance section. I think all of us would then agree to merge this as is.

François Daoust Removed definition of JSON-LD processors from the Conformance section
Other sections still mention JSON-LD processors, either to describe
how JSON-LD documents are processed or to put constraints on JSON-LD
processors through normative statements. Descriptive text would need
to link to the proper definition of JSON-LD processor in the API doc.
Normative statements that apply to JSON-LD processors need to be
dropped. All of this is being covered by issue #184.
f9f1b65
Contributor

tidoust commented Nov 9, 2012

I didn't pay attention to the fact that removing the definition of JSON-LD processor actually broke the layout of the document because ReSpec now complains that the document contains references to "JSON-LD processor" which is not defined. That's the good thing about ReSpec, it tells you when your document is not consistent ;)

I'm not sure how to proceed here. Should I rather:

  1. go ahead and try to remove all statements that involve "JSON-LD processor" as suggested in issue #184?
  2. remove all <tref> tags from the spec that target JSON-LD processor for the time being, leaving the text untouched?
  3. introduce a definition of "JSON-LD processor" in the terminology section?
    ... or do you prefer to take care of that on your own?
Member

lanthaler commented Nov 9, 2012

Please go ahead and try to remove all statements that involve "JSON-LD processor. I think most cases that should be rather trivial. Thanks for your help on this François.

François Daoust Dropped all references to "JSON-LD processor" from the text.
There remains one occurrence in a note on low-memory footprint
JSON-LD processors, but it is self-explanatory. Also another one
in the Microformat appendix but I'm not clear what the sentence
actually means.
c4649c9
Contributor

tidoust commented Nov 9, 2012

I removed all mentions of "JSON-LD processor" (save one in a self-describing note and one in the Microformat appendix).

I note that the resulting doc tends to use passive voice a bit too much, which effectively hide the need to use the term "JSON-LD processor" but still implies it. That's a common mistake:

Using a passive voice for describing the behavior, e.g. “an invalid XML file must be ignored” — this hides what product is supposed to follow the prescribed behavior.
http://www.w3.org/TR/test-methodology/#common-mistakes

Said differently, I find that the doc is still not clear as to how exactly a JSON-LD document maps to a JSON-LD graph (well, dataset when we have that notion in the doc). I'll try to find time to propose something concrete but suggest to stop here for this series of edits (unless you have further comments on the edits proposed, that is).

Member

lanthaler commented Nov 9, 2012

Thanks, I'll put up a proposal in the issue to merge this.

François Daoust JSON-LD document definition: dropped reference to Linked Data.
"Linked Data" is not normatively defined so shouldn't be referenced
from the JSON-LD document definition in the Conformance section. I
had put the reference only to have some informative description of
what a JSON-LD document is, but that's already expressed in the
introduction anyway.
32794ee

@lanthaler lanthaler added a commit that referenced this pull request Nov 13, 2012

@lanthaler lanthaler Merge pull request #194 from tidoust/master
Conformance section and grammar updates
89cdfa6

@lanthaler lanthaler merged commit 89cdfa6 into json-ld:master Nov 13, 2012

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