Add the ordered option for controlling elements of the framing algorithm.

For w3c/json-ld-api#8.

(cherry picked from commit 42b1aae)

Author: gkellogg

index.html

@@ -1015,10 +1015,8 @@ <h3>Framing Algorithm</h3>
     using the <a href="#frame-matching">Frame Matching algorithm</a>
     with <var>state</var>, <var>subjects</var>, <var>frame</var>, and <var>requireAll</var>.</li>
   <li>For each <var>id</var> and associated <a>node object</a> <var>node</var>
-    from the set of matched subjects, ordered by <var>id</var>:
-    <p class="ednote">Can we remove sorting, or make it subject to a processing
-      flag? In general, sorting is a performance problem for JSON-LD, and
-      inhibits stream processing.</p>
+    from the set of matched subjects, ordered lexographically by <var>id</var>
+    <span class="changed">if the optional <a data-link-for="JsonLdOptions">ordered</a> flag is <code>true</code></span>:
     <ol>
       <li>Initialize <var>output</var> to a new <a>dictionary</a> with <code>@id</code> and <var>id</var>.</li>
       <li>Otherwise, if <var>embed</var> is <code>@never</code> or if a
@@ -1056,7 +1054,8 @@ <h3>Framing Algorithm</h3>
               </li>
             </ol>
           </li>
-          <li>For each <var>property</var> and <var>objects</var> in <var>node</var>, ordered by <var>property</var>:
+          <li>For each <var>property</var> and <var>objects</var> in <var>node</var>, ordered lexographically by <var>property</var>
+            <span class="changed">if the optional <a data-link-for="JsonLdOptions">ordered</a> flag is <code>true</code></span>:
             <ol>
               <li>If <var>property</var> is a <a>keyword</a>, add <var>property</var> and <var>objects</var>
                 to <var>output</var>.</li>
@@ -1322,14 +1321,16 @@ <h3>JsonLdProcessor</h3>
         following steps are then executed asynchronously.</li>
       <li>Set <var>expanded input</var> to the result of using the
         <a data-cite="JSON-LD11-API#dom-jsonldprocessor-expand">expand</a>
-        method using <a data-lt="JsonLdProcessor-frame-input">input</a> and <a data-lt="JsonLdProcessor-frame-options">options</a>.
+        method using <a data-lt="JsonLdProcessor-frame-input">input</a> and <a data-lt="JsonLdProcessor-frame-options">options</a>
+        <span class="changed">with <a data-link-for="JsonldOptions">ordered</a> set to <code>false</code></span>.
       <li>Set <var>expanded frame</var> to the result of using the
         <code class="idlMemberName"><a data-cite="JSON-LD11-API#dom-jsonldprocessor-expand">expand</a></code>
         method using
         <a data-lt="JsonLdProcessor-frame-frame">frame</a> and
         <a data-lt="JsonLdProcessor-frame-options">options</a> with
-        <code class="idlMemberName"><a data-cite="JSON-LD11-API#dom-jsonldoptions-expandcontext">expandContext</a></code> set to <code>null</code>
-        and the <a data-cite="JSON-LD11-API#dom-jsonldoptions-frameexpansion">frameExpansion</a> option set to <code>true</code>.
+        <code class="idlMemberName"><a data-cite="JSON-LD11-API#dom-jsonldoptions-expandcontext">expandContext</a></code> set to <code>null</code>,
+        the <a data-cite="JSON-LD11-API#dom-jsonldoptions-frameexpansion">frameExpansion</a> option set to <code>true</code>,
+        <span class="changed">and the <a data-link-for="JsonldOptions">ordered</a> option set to <code>false</code></span>.
       <li>Set <var>context</var> to the value of <code>@context</code>
         from <a data-lt="JsonLdProcessor-frame-frame">frame</a>, if it exists, or to
         a new empty <a>context</a>, otherwise.</li>
@@ -1426,11 +1427,12 @@ <h3>JsonLdOptions</h3>
     <pre class="idl" data-transform="unComment"><!--
       dictionary JsonLdOptions {
         (JsonLdEmbed or boolean)  embed = "@last";
-        boolean explicit    = false;
-        boolean omitDefault = false;
-        boolean omitGraph;
-        boolean requireAll  = false;
-        boolean frameDefault  = false;
+        boolean                   explicit    = false;
+        boolean                   omitDefault = false;
+        boolean                   omitGraph;
+        boolean                   requireAll  = false;
+        boolean                   frameDefault  = false;
+        boolean                   ordered = false;
       };
 
       enum JsonLdEmbed {
@@ -1467,6 +1469,11 @@ <h3>JsonLdOptions</h3>
         <a href="#framing-algorithm">Framing Algorithm</a>.</dd>
       <dt><dfn data-dfn-for="JsonLdOptions">frameDefault</dfn></dt>
       <dd>Instead of framing a <var>merged graph</var>, frame only the <a>default graph</a>.</dd>
+      <dt class="changed"><dfn data-dfn-for="JsonLdOptions">ordered</dfn></dt>
+      <dd class="changed">If set to <code>true</code>, certain algorithm
+        processing steps where indicated are ordered lexicographically.
+        If <code>false</code>, order
+        is not considered in processing.</dd>
     </dl>
 
     <p><dfn>JsonLdEmbed</dfn> enumerates the values of the <a data-link-for="JsonLdOptions">embed</a> option:</p>
@@ -1603,12 +1610,23 @@ <h2>Changes since 1.0 Draft of 30 August 2012</h2>
     <li>Added the <a>omit default flag</a>, controled via the
       <a data-link-for="JsonLdOptions">omitDefault</a> API option and/or
       the current <a>processing mode</a>.</li>
+    <li>The API now adds an <a data-link-for="JsonLdOptions">ordered</a>
+       option, defaulting to <code>false</code> This is used in algorithms to
+       control interation of <a>dictionary member</a> keys. Previously, the
+       algorithms always required such an order. The instructions for
+       evaluating test results have been updated accordingly.</li>
   </ul>
 </section>
 
 <section class="appendix informative" id="changes-from-cg">
   <h2>Changes since JSON-LD Community Group Final Report</h2>
-  <p>None.</p>
+  <ul>
+    <li>The API now adds an <a data-link-for="JsonLdOptions">ordered</a>
+       option, defaulting to <code>false</code> This is used in algorithms to
+       control interation of <a>dictionary member</a> keys. Previously, the
+       algorithms always required such an order. The instructions for
+       evaluating test results have been updated accordingly.</li>
+  </ul>
 </section>
 
 <section class="appendix informative">

tests/README.md

@@ -8,17 +8,34 @@ comprehensive JSON-LD testing solution for developers creating JSON-LD Processor
 # Design
 
 Tests are for _framing_:
-* _frame_ tests have _input_, _frame_ and _expected_ documents. The _expected_ results can be compared using JSON object comparison with the processor output. For *NegativeEvaluationTests*, the result is a string associated with the expected error code.
+
+* _frame_ tests have _input_, _frame_ and _expected_ documents. The _expected_ results can be compared using [JSON-LD object comparison](#json-ld-object-comparison) with the processor output. Additionally, if the `ordered` option is not set, result should be expanded and compared with the expanded _expected_ document also using [JSON-LD object comparison](#json-ld-object-comparison).
+
+  For *NegativeEvaluationTests*, the result is a string associated with the expected error code.
 
 Unless `processingMode` is set explicitly in a test entry, `processingMode` is compatible with both `json-ld-1.0` and `json-ld-1.1`.
 
 Test results that include a context input presume that the context is provided locally, and not from the referenced location, thus the results will include the content of the context file, rather than a reference.
 
+## JSON-LD Object comparison
+
+If algorithms are invoked with the `ordered` flag set to `true`, simple JSON Object comparison may be used, as the order of all arrays will be preserved (except for _fromRdf_, unless the input quads are also ordered). If `ordered` is `false`, then the following algorithm will ensure arrays other than values of `@list` are compared without regard to order.
+
+JSON-LD Object comparison compares JSON objects, arrays, and values recursively for equality.
+
+* JSON objects are compared member by member without regard to the ordering of members within the object. Each member must have a corresponding member in the object being compared to. Values are compared recursively.
+* JSON arrays are generally compared without regard to order (the lone exception being if the referencing key is `@list`). Each item within the array must be equivalent to an item in the array being compared to by using the comparison algorithm recursively. For values of `@list`, the order of these items is significant.
+* JSON values are compared using strict equality.
+
+Note that some tests require re-expansion and comparison, as list values may exist as values of properties that have `@container: @list` and the comparison algorithm will not consider ordering significant.
+
 # Running tests
+
 Implementations create their own infrastructure for running the test suite. In particular, the following should be considered:
 
 * Some algorithms, may not preserve the order of statements listed in the input document, and provision should be taken for performing unordered array comparison, for arrays other than values of `@list`. (This may be difficult for compacted results, where array value ordering is dependent on the associated term definition).
 * Some implementations may choose an alternative Blank Node Label algorithm, the comparison between documents containing blank node labels should take this into consideration. (One way to do this may be to reduce both results and _expected_ to datsets to extract a bijective mapping of blank node labels between the two datasets as described in [RDF Dataset Isomorphism](https://www.w3.org/TR/rdf11-concepts/#dfn-dataset-isomorphism)).
+
 # Contributing
 
 If you would like to contribute a new test or a fix to an existing test,