Clarify "list of lists" feature at risk marker
authorMarkus Lanthaler <mark_lanthaler@gmx.net>
Sun, 11 Aug 2013 23:07:12 +0200
changeset 1859 6c82491551c6
parent 1858 c42e63624d47
child 1860 47c6b50bcfff
Clarify "list of lists" feature at risk marker

List of lists using the @list construct are still not supported.
spec/latest/json-ld-api/index.html
spec/latest/json-ld/index.html
--- a/spec/latest/json-ld-api/index.html	Sun Aug 11 22:40:18 2013 +0200
+++ b/spec/latest/json-ld-api/index.html	Sun Aug 11 23:07:12 2013 +0200
@@ -4141,23 +4141,25 @@
       <p>The <a>JsonLdErrorCode</a> represents the collection of valid JSON-LD error
         codes.</p>
 
-      <div class="issue atrisk" title="Lists of lists and partial list conversion from RDF">
-      <p class="atrisk-head">Note: This feature is
-        <a href="http://www.w3.org/2005/10/Process-20051014/tr#cfi">"at risk"</a> and may
-        be removed from this specification based on feedback. Please send feedback to
-        <a href="mailto:[email protected]">[email protected]w3.org</a>.
-        For the current status see
-        <a href="http://www.w3.org/2011/rdf-wg/wiki/JSON-LD_Features_at_Risk">features "at risk" in JSON-LD 1.0</a></p>
-      <p>While this document asserts that lists of lists are not
-          allowed in JSON-LD, new updates to the JSON-LD algorithms do support
-          lists of lists.
-          Implementors are asked to pay particular attention to the
-          feature and provide feedback on lists of lists and partial lists.
-          The feature may remain in
-          the specification, or it may be removed after further implementation
-          experience has been gathered. Similarly, partial list conversion in
-          the RDF algorithms have been marked as a feature at risk and may be
-          removed from the specification based on implementation feedback.</p>
+      <div class="issue atrisk" data-number="4" title="Lists of lists and partial list conversion from RDF">
+        <p class="atrisk-head">Note: This feature is
+          <a href="http://www.w3.org/2005/10/Process-20051014/tr#cfi">"at risk"</a> and may
+          be removed from this specification based on feedback. Please send feedback to
+          <a href="mailto:[email protected]">[email protected]</a>.
+          For the current status see
+          <a href="http://www.w3.org/2011/rdf-wg/wiki/JSON-LD_Features_at_Risk">features "at risk" in JSON-LD 1.0</a></p>
+       <p>The JSON-LD algorithms have been updated to support conversion of lists
+          of lists to <tref title="list object">list objects</tref> by preserving
+          the blank node head of the inner list. Lists of lists can, however, not be
+          represented directly in JSON-LD using the <code>@list</code> construct;
+          they have to be represented as a set of interlinked node objects using
+          RDF's rdf:first and rdf:rest properties. Implementors are asked to pay
+          particular attention to the feature and provide feedback on lists of lists
+          and partial lists. The feature may remain in the specification, or it may
+          be removed after further implementation experience has been gathered.
+          Similarly, partial list conversion in the RDF algorithms have been marked
+          as a feature at risk and may be removed from the specification based
+          on implementation feedback.</p>
       </div>
 
       <dl title="enum JsonLdErrorCode" class="idl">
--- a/spec/latest/json-ld/index.html	Sun Aug 11 22:40:18 2013 +0200
+++ b/spec/latest/json-ld/index.html	Sun Aug 11 23:07:12 2013 +0200
@@ -34,7 +34,7 @@
       // if this is a LCWD, uncomment and set the end of its review period
       lcEnd: "2009-08-05",
       crEnd: "2013-09-19",
-      
+
       issueBase: "https://github.com/json-ld/json-ld.org/issues/",
       // atRiskBase: "https://github.com/json-ld/json-ld.org/issues/",
 
@@ -170,7 +170,7 @@
     <li>Support processing of documents with a <code>+json</code> media type as defined in
       [[RFC6839]]</li>
     <li>Added a brief description of the data model to the introduction.</li>
-    <li>Fixed a number of document readability and flow issues related to all 
+    <li>Fixed a number of document readability and flow issues related to all
       of the updates made over the last several moths.</li>
   </ul>
 </section>
@@ -248,14 +248,14 @@
 
     <p>To understand the basics in this specification you must first be familiar with
       JSON, which is detailed in [[!RFC4627]].</p>
-      
-    <p>This document almost exclusively uses the term IRI 
-    (<a href="http://www.w3.org/TR/ld-glossary/#internationalized-resource-identifier">Internationalized Resource Indicator</a>) 
-    when discussing hyperlinks. Many Web developers are more familiar with the 
-    URL (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-locator">Uniform Resource Locator</a>) 
-    terminology. The document also uses, albeit rarely, the URI 
-    (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-identifier">Uniform Resource Indicator</a>) 
-    terminology. While these terms are often used interchangeably among 
+
+    <p>This document almost exclusively uses the term IRI
+    (<a href="http://www.w3.org/TR/ld-glossary/#internationalized-resource-identifier">Internationalized Resource Indicator</a>)
+    when discussing hyperlinks. Many Web developers are more familiar with the
+    URL (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-locator">Uniform Resource Locator</a>)
+    terminology. The document also uses, albeit rarely, the URI
+    (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-identifier">Uniform Resource Indicator</a>)
+    terminology. While these terms are often used interchangeably among
     technical communities, they do have important distinctions from one
     another and the specification goes to great lengths to try and use the
     proper terminology at all times.
@@ -285,7 +285,7 @@
    <dd>The JSON-LD syntax is very terse and human readable, requiring as
     little effort as possible from the developer.</dd>
    <dt>Zero Edits, most of the time</dt>
-   <dd>JSON-LD ensures a smooth and simple transition from existing 
+   <dd>JSON-LD ensures a smooth and simple transition from existing
      JSON-based systems. In many cases,
      zero edits to the JSON document and the addition of one line to the HTTP response
      should suffice (see <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>).
@@ -293,11 +293,11 @@
      already deployed large JSON-based infrastructure to use JSON-LD's features
      in a way that is not disruptive to their day-to-day operations and is
      transparent to their current customers. However, there are times where
-     mapping JSON to a graph representation is a complex undertaking. 
-     In these instances, rather than extending JSON-LD to support 
-     esoteric use cases, we chose not to support the use case. While Zero 
-     Edits is a design goal, it is not always possible without adding 
-     great complexity to the language. JSON-LD focuses on simplicity when 
+     mapping JSON to a graph representation is a complex undertaking.
+     In these instances, rather than extending JSON-LD to support
+     esoteric use cases, we chose not to support the use case. While Zero
+     Edits is a design goal, it is not always possible without adding
+     great complexity to the language. JSON-LD focuses on simplicity when
      possible.</dd>
     <dt>Usable as RDF</dt>
     <dd>JSON-LD is usable by developers as
@@ -357,27 +357,27 @@
 
   <section class="informative">
     <h2>Data Model Overview</h2>
-    
+
     <p>Generally speaking, the data model used for JSON-LD is a labeled,
-      directed <tref>graph</tref>. The graph contains 
-      <tref title="node">nodes</tref>, which are connected by 
-      <tref title="edge">edges</tref>. A <tref>node</tref> is typically data 
-      such as a <tref>string</tref>, <tref>number</tref>, 
-      <tref title="typed value">typed values</tref> (like dates and times) 
-      or an <tref>IRI</tref>. 
+      directed <tref>graph</tref>. The graph contains
+      <tref title="node">nodes</tref>, which are connected by
+      <tref title="edge">edges</tref>. A <tref>node</tref> is typically data
+      such as a <tref>string</tref>, <tref>number</tref>,
+      <tref title="typed value">typed values</tref> (like dates and times)
+      or an <tref>IRI</tref>.
       There is also a special class of <tref>node</tref> called a
       <tref>blank node</tref>, which is typically used to express data that does
-      not have a global identifier like an <tref>IRI</tref>. 
-      <tref title="blank node">Blank nodes</tref> are identified using a 
+      not have a global identifier like an <tref>IRI</tref>.
+      <tref title="blank node">Blank nodes</tref> are identified using a
       <tref>blank node identifier</tref>. This simple data model is incredibly
-      flexible and powerful, capable of modeling almost any kind of 
+      flexible and powerful, capable of modeling almost any kind of
       data. For a deeper explanation of the data model, see
       section <a href="#data-model"></a>.
     </p>
-    
-    <p>Developers who are familar with Linked Data technologies will 
+
+    <p>Developers who are familar with Linked Data technologies will
     recognize the data model as the RDF Data Model. To dive deeper into how
-    JSON-LD and RDF are related, see 
+    JSON-LD and RDF are related, see
     section <a href="#relationship-to-rdf"></a>.
     </p>
   </section>
@@ -474,8 +474,8 @@
     It is easy to parse and easy to generate. However, it is difficult to integrate JSON
     from different sources as the data may contain keys that conflict with other
     data sources. Furthermore, JSON has no
-    built-in support for hyperlinks, which are a fundamental building block on 
-    the Web. Let's start by looking at an example that we will be using for the 
+    built-in support for hyperlinks, which are a fundamental building block on
+    the Web. Let's start by looking at an example that we will be using for the
     rest of this section:</p>
 
   <pre class="example" data-transform="updateExample"
@@ -489,7 +489,7 @@
   -->
   </pre>
 
-  <p>It's obvious to humans that the data is about a person whose 
+  <p>It's obvious to humans that the data is about a person whose
     <code>name</code> is "Manu Sporny"
     and that the <code>homepage</code> property contains the URL of that person's homepage.
     A machine doesn't have such an intuitive understanding and sometimes,
@@ -499,9 +499,9 @@
 
   <p>Linked Data, and the Web in general, uses <tref title="IRI">IRIs</tref>
     (Internationalized Resource Identifiers as described in [[!RFC3987]]) for unambiguous
-    identification. The idea is to use <tref title="IRI">IRIs</tref> 
+    identification. The idea is to use <tref title="IRI">IRIs</tref>
     to assign unambiguous identifiers to data that may be of use to other developers.
-    It is useful for <tref title="term">terms</tref>, 
+    It is useful for <tref title="term">terms</tref>,
     like <code>name</code> and <code>homepage</code>, to expand to <tref title="IRI">IRIs</tref>
     so that developers don't accidentally step on each other's terms. Furthermore, developers and
     machines are able to use this <tref>IRI</tref> (by using a web browser, for instance) to go to
@@ -533,8 +533,8 @@
     <h2>The Context</h2>
 
     <p>When two people communicate with one another, the conversation takes
-    place in a shared environment, typically called 
-    "the context of the conversation". This shared context allows the 
+    place in a shared environment, typically called
+    "the context of the conversation". This shared context allows the
     individuals to use shortcut terms, like the first name of a mutual friend,
     to communicate more quickly but without losing accuracy. A context in
     JSON-LD works in the same way. It allows two applications to use shortcut
@@ -562,7 +562,7 @@
         },
         "homepage": {
           "@id": "http://schema.org/url", **** ← This means that 'homepage' is shorthand for 'http://schema.org/url' ****
-          "@type": "@id" **** ← This means that the value associated with 'homepage' should be interpreted as an identifier that is an IRI **** 
+          "@type": "@id" **** ← This means that the value associated with 'homepage' should be interpreted as an identifier that is an IRI ****
         }
       }****
     }
@@ -649,9 +649,9 @@
     }
     -->
     </pre>
-    
+
     <p>This section only covers the most basic features of the JSON-LD
-    Context. More advanced features related to the JSON-LD Context are covered 
+    Context. More advanced features related to the JSON-LD Context are covered
     in section <a href="#advanced-concepts"></a>.
     </p>
   </section>
@@ -767,7 +767,7 @@
 
   <p>In the example above, even though the value <code>http://manu.sporny.org/</code>
     is expressed as a JSON <tref>string</tref>, the type <tref>coercion</tref>
-    rules will transform the value into an IRI when processing the data. 
+    rules will transform the value into an IRI when processing the data.
     See <a class="sectionRef" href="#type-coercion"></a> for more
     details about this feature.</p>
 
@@ -786,10 +786,10 @@
   </ol>
 
   <p>This section only covers the most basic features associated with IRIs
-  in JSON-LD. More advanced features related to IRIs are covered in 
+  in JSON-LD. More advanced features related to IRIs are covered in
   section <a href="#advanced-concepts"></a>.
   </p>
-  
+
 </section>
 
 <section class="informative">
@@ -826,8 +826,8 @@
   <p>The example above contains a <tref>node object</tref> identified by the IRI
     <code>http://me.markus-lanthaler.com/</code>.</p>
 
-  <p>This section only covers the most basic features associated with 
-  node identifiers in JSON-LD. More advanced features related to 
+  <p>This section only covers the most basic features associated with
+  node identifiers in JSON-LD. More advanced features related to
   node identifiers are covered in section <a href="#advanced-concepts"></a>.
   </p>
 
@@ -883,8 +883,8 @@
 -->
 </pre>
 
-<p>This section only covers the most basic features associated with 
-types in JSON-LD. More advanced features related to 
+<p>This section only covers the most basic features associated with
+types in JSON-LD. More advanced features related to
 types are covered in section <a href="#advanced-concepts"></a>.
 </p>
 
@@ -2063,23 +2063,25 @@
   This decision was made due to the extreme amount of added complexity when
   processing lists of lists.</p>
 
-<div class="issue atrisk" title="Lists of lists and partial list conversion from RDF">
-<p class="atrisk-head">Note: This feature is
-  <a href="http://www.w3.org/2005/10/Process-20051014/tr#cfi">"at risk"</a> and may
-  be removed from this specification based on feedback. Please send feedback to
-  <a href="mailto:[email protected]">[email protected]</a>.
-  For the current status see
-  <a href="http://www.w3.org/2011/rdf-wg/wiki/JSON-LD_Features_at_Risk">features "at risk" in JSON-LD 1.0</a></p>
-<p>While this document asserts that lists of lists are not
-    allowed in JSON-LD, new updates to the JSON-LD algorithms do support
-    lists of lists. 
-    Implementors are asked to pay particular attention to the
-    feature and provide feedback on lists of lists and partial lists. 
-    The feature may remain in
-    the specification, or it may be removed after further implementation 
-    experience has been gathered. Similarly, partial list conversion in
-    the RDF algorithms have been marked as a feature at risk and may be 
-    removed from the specification based on implementation feedback.</p>
+<div class="issue atrisk" data-number="4" title="Lists of lists and partial list conversion from RDF">
+  <p class="atrisk-head">Note: This feature is
+    <a href="http://www.w3.org/2005/10/Process-20051014/tr#cfi">"at risk"</a> and may
+    be removed from this specification based on feedback. Please send feedback to
+    <a href="mailto:[email protected]">[email protected]</a>.
+    For the current status see
+    <a href="http://www.w3.org/2011/rdf-wg/wiki/JSON-LD_Features_at_Risk">features "at risk" in JSON-LD 1.0</a></p>
+ <p>The JSON-LD algorithms have been updated to support conversion of lists
+    of lists to <tref title="list object">list objects</tref> by preserving
+    the blank node head of the inner list. Lists of lists can, however, not be
+    represented directly in JSON-LD using the <code>@list</code> construct;
+    they have to be represented as a set of interlinked node objects using
+    RDF's rdf:first and rdf:rest properties. Implementors are asked to pay
+    particular attention to the feature and provide feedback on lists of lists
+    and partial lists. The feature may remain in the specification, or it may
+    be removed after further implementation experience has been gathered.
+    Similarly, partial list conversion in the RDF algorithms have been marked
+    as a feature at risk and may be removed from the specification based
+    on implementation feedback.</p>
 </div>
 
 <p>While <code>@list</code> is used to describe <em>ordered lists</em>,