Reorganization syntax document #47

gkellogg · 2018-08-15T18:37:02Z

This is a stab at updating the syntax document to create feature-related sections. I also attempt to clarify some terms.

Preview | Diff

BigBlueHat

Just a wee whitespace fix. Otherwise, I do like the new organization and think it focuses reading better that before.

BigBlueHat · 2018-08-15T19:02:54Z

index.html

-  "****@type****": ****[ "http://schema.org/Restaurant", "http://schema.org/Brewery" ]****####,
+  "@id": "http://me.markus-lanthaler.com/",
+  "@type": ****[****"
+     http://schema.org/Person",


Whitespace broke the data(base) star. 😉

Travis was mostly right...it's Example 14 though, not 13 per Travis:
https://pr-preview.s3.amazonaws.com/w3c/json-ld-syntax/pull/47.html#x3-4-specifying-the-type

Matching example numbering in an external script is challenging, and I'll need to look into that more later.

Actually, numbering seems to be off because of the example in typographical conventions, which isn't considered by the script, as it's in an included file. It may just be an off-by-one problem, but changing that to use Example 0 might make sense anyway.

Fixed broken example

davidlehn · 2018-08-16T04:06:09Z

index.html

@@ -237,7 +237,7 @@ <h2>How to Read this Document</h2>
      <li>Software developers who want to implement processors and APIs for
        JSON-LD</li>
      <li>Software developers who want to generate or consume Linked Data,
-        an RDF graph, or an <a>RDF Dataset</a> in a JSON syntax</li>
+        an RDF <a>graph</a>, or an <a>Dataset</a> in a JSON syntax</li>


"a Dataset"

The official terminology is indeed "RDF Dataset" alongside with "RDF graph". The term "Dataset" may be considered as too ambiguous. I would prefer keep this as is.

davidlehn · 2018-08-16T04:10:09Z

index.html

-      <!--<li><a href="https://json-ld.org/minutes/">Public teleconferences</a> are held
-        on Tuesdays at 1500UTC on the second and fourth week of each month.</li> -->
+      <li>Technical discussion typically occurs on the working group mailing list:
+        <a href="https://lists.w3.org/Archives/Public/public-json-ld-wg/">public-json-ld-wg@w3.org</a></li>

      <li>The <a href="https://webchat.freenode.net/?channels=json-ld">#json-ld</a>
        IRC channel is available for real-time discussion on irc.freenode.net.</li>


Should update this to the w3c wg channel or perhaps list both?

I'd say list both.

@iherman is there a URL to reference the #json-ld channel on irc.w3.org directly?

http://irc.w3.org/?channels=json-ld for the Web-based IRC client or irc://irc.w3.org/#json-ld for those with irc:// protocol handlers installed properly.

davidlehn · 2018-08-16T04:11:03Z

index.html

+      or an <a>IRI</a>.</p>
+    <p class="changed">Within a directed graph, nodes with may
+      be <em>unnamed</em>, i.e., not identified by an <a>IRI</a> or representing
+      a data such as <a>strings</a> or <a>numbers</a>. Such nodes are called <a>blank nodes</a>,


"a data" -> "data"

davidlehn · 2018-08-16T04:14:41Z

index.html

@@ -454,7 +453,7 @@ <h2>Syntax Tokens and Keywords</h2>
      <dt class="changed"><code>@nest</code></dt><dd class="changed">Collects a set of <a>nested properties</a> within
        a <a>node object</a>.</dd>
      <dt class="changed"><code>@none</code></dt><dd class="changed">Used as an index value
-        in an id map, language map, type map or elsewhere where a dictionary is
+        in an <a>id map</a>, <a>language map</a>, <a>type map</a> or elsewhere where a dictionary is


Doc is mostly using oxford comma. Add one here.

... and the W3C style guides also ask for Oxford commas...:-)

I have a friend with an Oxford comma tatoo for situations just like this one. 😁 We should add one.

How do you tattoo an oxford comma?

Ink and a needle. Same as normal tatoos. 😉

davidlehn · 2018-08-16T04:18:35Z

index.html

-    in section <a href="#advanced-concepts" class="sectionRef"></a>.
-    </p>
+      Context. The Context can also be used to help interpret other more
+      complext JSON datastructures as Linked Data and to specify a context


typo: complext -> complex
typo: datastructures -> data structures

davidlehn · 2018-08-16T04:20:31Z

index.html

-    </p>
+      Context. The Context can also be used to help interpret other more
+      complext JSON datastructures as Linked Data and to specify a context
+      as part of an <a>expanded term definition</a>, to apply for values associated with that term.


This sentence is a bit difficult to read. May need some rewording.

Maybe should link "term" here too.

How about the following:

This section only covers the most basic features of the JSON-LD Context.
The Context can also be used to help interpret other more
complex JSON data structures, such as indexed values,
ordered values, and
nested properties.
More advanced features related to the JSON-LD Context are covered in
section ....

davidlehn · 2018-08-16T04:23:27Z

index.html

+  example, in the <em>schema.org</em> vocabulary, the <em>givenName</em>
+  property is associated with a <em>Person</em>. Therefore, one may reason that
+  if a <a>node object</a> contains the property <em>firstName</em>, that the
+  type is a <em>Person</em>; making this explicity with an explicit type helps


making -> marking?

davidlehn · 2018-08-16T04:24:50Z

index.html

+  property is associated with a <em>Person</em>. Therefore, one may reason that
+  if a <a>node object</a> contains the property <em>firstName</em>, that the
+  type is a <em>Person</em>; making this explicity with an explicit type helps
+  to clarify.</p>


trailing [english something something]... maybe use "to clarify the association."

davidlehn · 2018-08-16T04:27:22Z

index.html

-  the core functionality described above. The following section describes this
+  the core functionality described above. JSON can be used to express data
+  using a variety of different stuctures, and the features described in this
+  section can be used to interpret a variety of different JSON structures into


"to interpret a variety of different JSON structures" -> "to interpret those structures"

davidlehn · 2018-08-16T04:28:11Z

index.html

+  using a variety of different stuctures, and the features described in this
+  section can be used to interpret a variety of different JSON structures into
+  Linked Data. A JSON-LD processor will make use of provided and embedded
+  contexts to interpret property values in a number of different ideomatic


ideomatic -> idiomatic

davidlehn · 2018-08-16T04:29:16Z

index.html

+    definition. See <a href="#sets-and-lists" class="sectionRef"></a> for a
+    further discussion.</p></dd>
+  <dt>Property nesting</dt>
+  <dd><p>Another JSON idium often found in APIs is to use an


davidlehn · 2018-08-16T04:32:02Z

index.html

+      for those triples also having a common predicate. The result may
+      then be framed by using the
+      <a data-cite="JSON-LD11-FRAMING#framing-algorithm">Framing Algorithm</a>
+      described in [JSON-LD11-FRAMING] to create the desired object embedding.</p>


Need double brackets.

davidlehn · 2018-08-16T04:34:00Z

index.html

+      <code>http://greggkellogg.net/foaf</code> which could include a similar
+      representation.</p>
+
+    <p>A common idium found in JSON usage is objects being specified as the


davidlehn · 2018-08-16T04:34:11Z

index.html

+    <p>See <a href="#embedding" class="sectionRef"></a> details these relationships.</p>
+  </dd>
+  <dt>Indexed values</dt>
+  <dd><p>Another common idium in JSON is to use an intermediate object to represent property values via indexing. JSON-LD allows data to be indexed


davidlehn · 2018-08-16T04:50:16Z

index.html

+      href="#nested-properties" class="sectionRef"></a>.</p></dd>
+  <dt>Referencing objects</dt>
+  <dd>
+    <p>Linked data is all about describing the relationships between different objects.


davidlehn · 2018-08-16T04:56:39Z

index.html

+    <p>Linked data is all about describing the relationships between different objects.
+      Sometimes these relationships are between objects defined in different
+      documents described on the web, sometimes the resources are described
+      within the same document.</p>


Should probably switch whole para to use "resources" vs "objects".

davidlehn · 2018-08-16T04:58:55Z

index.html

+  <p>Section <a href="#the-context"></a> introduced the basics of what makes
+  JSON-LD work. This section expands on the basic principles of the
+  <a>context</a> and demonstrates how more advanced use cases can
+  be achieved using JSON-LD. </p>


Extra space before end tag.

davidlehn · 2018-08-16T04:59:30Z

index.html

+  <a>context</a> and demonstrates how more advanced use cases can
+  be achieved using JSON-LD. </p>
+
+  <p>In general, contexts may be used at any time a


Remove "at".

davidlehn · 2018-08-16T05:17:19Z

index.html

+  </pre>
+
+  <p>Setting <code>@base</code> to <a>null</a> will prevent
+    <a>relative IRIs</a> to be expanded to


"to be" -> "from being"

davidlehn · 2018-08-16T05:27:16Z

index.html

-    contexts, within the body of the document. Contexts linked via a
-    <code>http://www.w3.org/ns/json-ld#context</code> <a data-cite="RFC5988#section-5">HTTP Link Header</a> MUST be
-    ignored for such documents.</p>
+<p>The example shown above would generate the following data.</p>


davidlehn · 2018-08-16T05:31:51Z

index.html

+    which look like <a>IRIs</a> using an underscore (<code>_</code>)
+    as scheme. This allows one to reference the node locally within the document, but
+    makes it impossible to reference the node from an external document. The
+    <a>blank node identifier</a> is scoped  to the document in which it is used.</p>


Extra space after scoped.

iherman · 2018-08-16T07:21:39Z

@gkellogg I do like what you have done, but I would go a little bit further:

I think section 4 should stop with 4.8.
- 4.9-4.11 should be in their separate, top level section (ie, section 5). Up until that point, section 4 describes features of JSON-LD that I, as an author of data, would/could use when creating JSON-LD. If I am 'just' an author, I would not really care about expanding, compacting, or flattening; these are interesting for JSON-LD processors, but for an author. Hence they should be in a separate top level section.
- Same with 4.12 and 4.13. These are ways to set up how to consume JSON-LD not the way I would author data. I would argue it should be separated from the rest.
We did discuss whether the named graph section should be in its own top level section. With that organization that may not be necessary...

iherman · 2018-08-16T07:29:46Z

Is Example 66 correct? This is an example of a 'bush', but this means that the example context is not valid for the second graph. Ie, the value of "name" will not be valid. In other words Example 66 is not equivalent to Example 67...

<standard nag>We should really make it easier to encode bushes:-)</standard nag>

BigBlueHat · 2018-08-16T14:43:08Z

Is Example 66 correct? This is an example of a 'bush', but this means that the example context is not valid for the second graph. Ie, the value of "name" will not be valid. In other words Example 66 is not equivalent to Example 67...

True. At this point Example 66 doesn't output the second Person at all (see playground demo).

We should really make it easier to encode bushes:-)</standard nag>

If there's a shared @context, then isn't {"@context": "...", "@graph": [{}, {}, {}]} about as obvious as we can make it? I think the simple array-style for "bushes" works best when you have a bunch of JSON-LD document which may or may not have shared contexts, and you simply want to concatenate them. But this is decidedly off topic. 😄 But apparently still wants discussing. 😃

gkellogg · 2018-08-16T18:21:49Z

@davidlehn thanks for your detailed review and comments; some of these problems have been in the document for a while.

davidlehn · 2018-08-17T02:30:22Z

@gkellogg Yeah, I figured as long as I was reading the diffs I might as well suggest changes on the moved text too. I really didn't even think too much about the reorganization itself!

dlongley · 2018-08-17T15:06:09Z

Unfortunately, I don't have enough time to review this thoroughly right now, but I did skim it. Overall, I think it's an improvement to the structural reorganization of the advanced concepts and other latter sections. I'm a little concerned that we may have significantly upped the reading level with more complex language, but perhaps that can be addressed as needed in the future. It's good that the accessibility of the introduction and basic sections have been left as is.

azaroth42 · 2018-08-17T17:27:04Z

The new structure looks good to me. For FPWD it's already far better than most, so I think we should lock this one in. Further changes over time are obviously inevitable, and we can work on wording later in the WG.

gkellogg added the spec:editorial label Aug 15, 2018

gkellogg self-assigned this Aug 15, 2018

gkellogg requested review from BigBlueHat, davidlehn, iherman and azaroth42 August 15, 2018 18:37

Reorganize syntax document.

e01f461

gkellogg force-pushed the reorganization branch from e742d8c to e01f461 Compare August 15, 2018 18:38

BigBlueHat previously requested changes Aug 15, 2018

View reviewed changes

Fix broken whitespace in example.

344dde7

BigBlueHat approved these changes Aug 15, 2018

View reviewed changes

davidlehn reviewed Aug 16, 2018

View reviewed changes

Address comments and add section to describe "Framed Document Form".

f28cda2

Update WG IRC channel link.

d3ac68f

azaroth42 approved these changes Aug 17, 2018

View reviewed changes

gkellogg merged commit 8530193 into master Aug 17, 2018

gkellogg deleted the reorganization branch August 17, 2018 21:59

Reorganization syntax document #47

Reorganization syntax document #47

Uh oh!

Conversation

gkellogg commented Aug 15, 2018 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BigBlueHat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iherman commented Aug 16, 2018

Uh oh!

gkellogg commented Aug 15, 2018 •

edited by pr-preview bot

Loading