@@ -1606,7 +1610,8 @@
Algorithm
expanded value to the result of using this algorithm
recursively passing
active context,
@graph
for
active property,
value for
element,
-
and the frame expansion flag,
+
and the frameExpansion
+ and ordered flags,
ensuring that expanded value is an array of one or more dictionaries.
If expanded property is @value and
@@ -1620,7 +1625,7 @@ Algorithm
in this case as the meaning of an @type member depends
on the existence of an @value member.
- When the frame expansion flag is set, value
+ When the frameExpansion flag is set, value
may also be an empty dictionary or an array of
scalar values. expanded value will be null, or an
array of one or more scalar values.
@@ -1630,7 +1635,7 @@
Algorithm
error has been detected and processing is aborted.
Otherwise, set expanded value to lowercased value.
- When the frame expansion flag is set, value
+ When the frameExpansion flag is set, value
may also be an empty dictionary or an array of zero or
strings. expanded value will be an
array of one or more string values converted to lower case.
@@ -1647,14 +1652,16 @@
Algorithm
Otherwise, initialize expanded value to the result of using
this algorithm recursively passing active context,
active property, value for element,
- and the frame expansion flag.
+
and the frameExpansion
+ and ordered flags.
If expanded property is @set, set
expanded value to the result of using this algorithm
recursively, passing active context,
active property, value for element,
- and the frame expansion flag.
+
and the frameExpansion
+ and ordered flags.
If expanded property is @reverse and
value is not a dictionary, an
invalid @reverse value
@@ -1664,7 +1671,8 @@ Algorithm
algorithm recursively, passing active context,
@reverse as active property,
value as element,
- and the frame expansion flag.
+
and the frameExpansion
+ and ordered flags.
If expanded value contains an @reverse member,
i.e., properties that are reversed twice, execute for each of its
property and item the following steps:
@@ -1706,7 +1714,7 @@ Algorithm
add key to nests, initializing it to an empty array,
if necessary.
Continue with the next key from element.
-
When the frame expansion flag is set,
+ When the frameExpansion flag is set,
if expanded property is any other
framing keyword (@explicit, @default,
@embed, @explicit, @omitDefault, or
@@ -1715,7 +1723,8 @@ Algorithm
Expansion Algorithm
recursively, passing active context,
active property, value for element,
- and the frame expansion flag.
+
and the frameExpansion
+ and ordered flags.
Unless expanded value is null, set
the expanded property member of result to
expanded value.
@@ -1738,7 +1747,7 @@
Algorithm
Initialize expanded value to an empty
array.
For each key-value pair language-language value
- in value, ordered lexicographically by language:
+ in value, ordered lexicographically by language if ordered is true:
- If language value is not an array
set it to an array containing only
@@ -1773,7 +1782,8 @@
Algorithm
- Initialize expanded value to an empty
array.
- For each key-value pair index-index value
- in value, ordered lexicographically by index:
+ in value, ordered lexicographically by index
+ if ordered is
true:
- If container mapping includes
@type,
and index's term definition in
@@ -1796,7 +1806,8 @@ Algorithm
map context as active context,
key as active property,
index value as element,
- and the frame expansion flag.
+ and the frameExpansion
+ and ordered flags.
- For each item in index value:
- If container mapping includes
@@ -1839,7 +1850,8 @@
Algorithm
- Otherwise, initialize expanded value to the result of
using this algorithm recursively, passing term context as active context,
key for active property, value for element,
- and the frame expansion flag.
+ and the frameExpansion
+ and ordered flags.
- If expanded value is
null, ignore key
by continuing to the next key from element.
- If container mapping includes
@list and
@@ -1957,7 +1969,7 @@ Algorithm
- Otherwise, if result is a dictionary whose only
member is
@id, set result to null.
- When the frame expansion flag is set, a dictionary
+ When the frameExpansion flag is set, a dictionary
containing only the @id member is retained.
@@ -2129,10 +2141,14 @@
Overview
Algorithm
- The algorithm takes five required input variables: an active context,
- an inverse context, an active property, an
- element to be compacted, and a flag
- compactArrays
+
The algorithm takes four required and two optional input variables.
+ The required inputs are an active context,
+ an inverse context, an active property,
+ and an element to be compacted.
+ The optional inputs are the
+ compactArrays flag
+ and the ordered flag, used to order
+ dictionary member keys lexicographically, where noted.
To begin, the active context is set to the result of
performing Context Processing
on the passed context, the inverse context is
@@ -2141,9 +2157,8 @@
Algorithm
on active context, the active property is
set to null, element is set to the result of
performing the Expansion algorithm
- on the JSON-LD input, and, if not passed,
- compactArrays
- is set to true.
+ on the JSON-LD input.
+ If not passed, the both flags are set to false.
- If the term definition for active property has a
@@ -2167,8 +2182,10 @@
Algorithm
- Initialize compacted item to the result of using this
algorithm recursively, passing active context,
- inverse context, active property, and
- item for element.
+ inverse context, active property,
+ item for element,
+ and the compactArrays
+ and ordered flags.
- If compacted item is not
null, then append
it to result.
@@ -2195,10 +2212,12 @@ Algorithm
If element is a
list object, and the container mapping for
active property in active context is @list,
- return the esult of using this algorithm recursively, passing
+ return the result of using this algorithm recursively, passing
active context, inverse context,
- active property, and value of @list
- in element for element.
+ active property, value of @list
+ in element for element,
+ and the compactArrays
+ and ordered flags.
Initialize inside reverse to true if
active property equals @reverse,
otherwise to false.
@@ -2227,7 +2246,8 @@ Algorithm
For each key expanded property and value expanded value
- in element, ordered lexicographically by expanded property:
+ in element, ordered lexicographically by expanded property
+ if ordered is true:
- If expanded property is
@id or
@type:
@@ -2276,8 +2296,10 @@ Algorithm
- Initialize compacted value to the result of using this
algorithm recursively, passing active context,
inverse context,
@reverse for
- active property, and expanded value
- for element.
+ active property, expanded value
+ for element,
+ and the compactArrays
+ and ordered flags.
For each property and value in compacted value:
- If the term definition for property in the
@@ -2326,8 +2348,10 @@
Algorithm
- Initialize compacted value to the result of using this
algorithm recursively, passing active context,
inverse context, property for
- active property, and expanded value
- for element.
+ active property, expanded value
+ for element,
+ and the compactArrays
+ and ordered flags.
Add expanded value as the value of @preserve
in result unless expanded value is an empty array.
@@ -2420,7 +2444,9 @@ Algorithm
expanded item for element if it does
not contain the member @list
and is not a graph object containing @list,
- otherwise pass the value of the member for element.
+ otherwise pass the value of the member for element.
+ Along with the compactArrays
+ and ordered flags
If expanded item is a list object:
@@ -3409,9 +3435,13 @@ Overview
Algorithm
- The algorithm takes two input variables, an element to flatten and
- an optional context used to compact the flattened document. If not
- passed, context is set to null.
+ The algorithm takes one required and two optional input variables.
+ The required input is an element to flatten.
+ The optional inputs are the context used to compact the flattened document
+ and the ordered flag, used to order
+ dictionary member keys lexicographically, where noted.
+ If not passed, context is set to null
+ and, the ordered flag is set to false.
This algorithm generates new blank node identifiers
and relabels existing blank node identifiers.
@@ -3431,7 +3461,10 @@
Algorithm
member of node map, which is a dictionary representing
the default graph.
For each key-value pair graph name-graph in node map
- where graph name is not @default, perform the following steps:
+ where graph name is not @default,
+ ordered lexicographically by var>graph name
+ if ordered is true
+ perform the following steps:
- If default graph does not have a graph name member, create
one and initialize its value to a dictionary consisting of an
@@ -3440,18 +3473,21 @@
Algorithm
default graph using the variable entry.
- Add an
@graph member to entry and set it to an
empty array.
- - For each id-node pair in graph ordered by id,
+
- For each id-node pair in graph ordered lexicographically by id
+ if ordered is
true,
add node to the @graph member of entry,
unless the only member of node is @id.
Initialize an empty array flattened.
- For each id-node pair in default graph ordered by id,
+ For each id-node pair in default graph ordered lexicographically by id
+ if ordered is true,
add node to flattened,
unless the only member of node is @id.
If context is null, return flattened.
Otherwise, return the result of compacting flattened according the
Compaction algorithm passing context
+ and the ordered flag
ensuring that the compaction result has only the @graph keyword (or its alias)
at the top-level other than @context, even if the context is empty or if there is only one element to
put in the @graph array. This ensures that the returned
@@ -4078,9 +4114,11 @@ Overview
Algorithm
- The algorithm takes one required and two optional inputs: an RDF dataset dataset
- and the two flags use native types and use rdf:type
- that both default to false.
+ The algorithm takes one required and three optional inputs: an RDF dataset dataset
+ and the three flags use native types, use rdf:type,
+ and the ordered flag, used to order
+ dictionary member keys lexicographically, where noted
+ that all default to false.
- Initialize default graph to an empty dictionary.
@@ -4220,15 +4258,17 @@ Algorithm
Initialize an empty array result.
For each subject and node in default graph
- ordered by subject:
+ ordered lexographically by subject
+ if ordered is true:
- If graph map has a subject member:
- Add an
@graph member to node and initialize
its value to an empty array.
- For each key-value pair s-n in the subject
- member of graph map ordered by s, append n
- to the
@graph member of node after
+ member of graph map ordered lexographically by s
+ if ordered is true,
+ append n to the @graph member of node after
removing its usages member, unless the only
remaining member of n is @id.
@@ -4496,7 +4536,8 @@ The JsonLdProcessor Interface
following steps are then executed asynchronously.
- Set expanded input to the result of using the
expand
- method using input and options.
+ method using input and options,
+ with ordered set to
false.
- If context is a dictionary having an
@context member, set
context to that member's value, otherwise to context.
- Initialize an active context using context;
@@ -4512,7 +4553,9 @@
The JsonLdProcessor Interface
an empty dictionary as inverse context,
null as property,
expanded input as element, and if passed, the
- compactArrays flag in options.
+ compactArrays
+ and ordered
+ flags in options.
Fulfill the promise passing compacted output.
transforming compacted output from the
internal representation to a JSON serialization.
@@ -4579,7 +4622,10 @@ The JsonLdProcessor Interface
Set expanded output to the result of using the
Expansion algorithm, passing the
active context and input as element,
- and, if the frameExpansion option is set, pass the frame expansion flag as true..
+ and if passed, the
+ frameExpansion
+ and ordered
+ flags in options.
Fulfill the promise passing expanded output.
transforming expanded output from the
internal representation to a JSON serialization.
@@ -4606,7 +4652,8 @@ The JsonLdProcessor Interface
following steps are then executed asynchronously.
Set expanded input to the result of using the
expand
- method using input and options.
+ method using input and options
+ with ordered set to false.
If context is a dictionary having an @context member, set
context to that member's value, otherwise to context.
Initialize an active context using context;
@@ -4623,9 +4670,9 @@ The JsonLdProcessor Interface
Set flattened output to the result of using the
Flattening algorithm, passing
expanded input as element, active context, and if passed, the
- compactArrays flag in options
- (which is internally passed to the
- Compaction algorithm).
+ compactArrays
+ and ordered
+ flags in options.
Fulfill the promise passing flattened output.
transforming flattened output from the
internal representation to a JSON serialization.
@@ -4688,6 +4735,7 @@ The JsonLdOptions Type
LoadDocumentCallback documentLoader = null;
(JsonLdDictionary? or USVString) expandContext = null;
boolean frameExpansion = false;
+ boolean ordered = false;
USVString processingMode = null;
boolean produceGeneralizedRdf = true;
};
@@ -4729,6 +4777,11 @@ The JsonLdOptions Type
base option or document location when compacting.
frameExpansion
Enables special frame processing rules for the Expansion Algorithm.
+ ordered
+ If set to true, certain algorithm
+ processing steps where indicated are ordered lexicographically.
+ If false, order
+ is not considered in processing.
@@ -5016,7 +5069,7 @@
Changes since 1.0 Recommendation of 16 January 2014
- The Expansion Algorithm
has a special processing mode, based on
- the frame expansion flag, to enable content associated with JSON-LD
+ the frameExpansion flag, to enable content associated with JSON-LD
frames, which may not otherwise be valid JSON-LD documents.
- An expanded term definition can now have an
@context member, which defines a context used for values of
@@ -5081,6 +5134,11 @@ Changes since 1.0 Recommendation of 16 January 2014
has been updated to ensure that only well-formed triples
are emitted; previously, it only ensured that triples containing
relative IRIs were excluded.
+ - The API now adds an ordered
+ option, defaulting to
false This is used in algorithms to
+ control interation of dictionary member keys. Previously, the
+ algorithms always required such an order. The instructions for
+ evaluating test results have been updated accordingly.
@@ -5092,6 +5150,11 @@
Changes since JSON-LD Community Group Final Report
has been updated to ensure that only
well-formed triples
are emitted; previously, it only ensured that
triples containing
relative IRIs were excluded.
+
The API now adds an ordered
+ option, defaulting to false This is used in algorithms to
+ control interation of dictionary member keys. Previously, the
+ algorithms always required such an order. The instructions for
+ evaluating test results have been updated accordingly.
diff --git a/tests/README.md b/tests/README.md
index 4fb30422..11feeb63 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -8,27 +8,57 @@ comprehensive JSON-LD testing solution for developers creating JSON-LD Processor
# Design
Tests are defined into _compact_, _expand_, _flatten_, _remote-doc_, _fromRdf_, and _toRdf_ sections:
-* _compact_ tests have _input_, _expected_ and _context_ 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.
-* _expand_ tests have _input_ 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.
-* _flatten_ tests have _input_ 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.
-* _remote-doc_ tests have _input_ 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. Options may be present to describe the intended HTTP behavior:
+
+* _compact_ tests have _input_, _expected_ and _context_ 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.
+* _expand_ tests have _input_ and _expected_ documents.
+ The _expected_ results can be compared using [JSON-LD object comparison](#json-ld-object-comparison) with the processor output.
+
+ For *NegativeEvaluationTests*, the result is a string associated with the expected error code.
+* _flatten_ tests have _input_ and _expected_ documents and an optional _context_ document.
+ The _expected_ results can be compared using [JSON-LD object comparison](#json-ld-object-comparison) with the processor output.
+ Additionally, if the result is compacted and 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.
+* _remote-doc_ tests have _input_ and _expected_ documents.
+ The _expected_ results can be compared using [JSON-LD object comparison](#json-ld-object-comparison) with the processor output.
+
+ For *NegativeEvaluationTests*, the result is a string associated with the expected error code. Options may be present to describe the intended HTTP behavior:
* _contentType_: Content-Type of the returned HTTP payload, defaults to the appropriate type for the _input_ suffix.
* _httpStatus_: The HTTP status code to return, defaults to `200`.
* _redirectTo_: The HTTP _Content-Location_ header value.
* _httpLink_: The HTTP _Link_ header value.
-* _fromRdf_ tests have _input_ and _expected_ documents. The _expected_ results can be compared using JSON object comparison with the processor output. Note that comparison of JSON Arrays should consider the fact that statements in an RDF Dataset are unordered, and therefore, properties with multiple values, and the value of `@graph` may not be ordered as in the _expected_ document and blank node labels may not be preserved.
-* _toRdf_ tests have _input_ and _expected_ documents. The _expected_ results can be compared using [RDF Dataset Isomorphism](https://www.w3.org/TR/rdf11-concepts/#dfn-dataset-isomorphism).
+* _fromRdf_ tests have _input_ and _expected_ documents.
+ The _expected_ results can be compared using [JSON-LD object comparison](#json-ld-object-comparison) with the processor output.
+* _toRdf_ tests have _input_ and _expected_ documents.
+ The _expected_ results can be compared using [RDF Dataset Isomorphism](https://www.w3.org/TR/rdf11-concepts/#dfn-dataset-isomorphism).
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:
* _remote-doc_ tests will likely not return expected HTTP headers, so the _options_ should be used to determine what headers are associated with the input document.
* Some algorithms, particularly _fromRdf_, 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,