feat (cli): Canonicalization of JSON-LD ordered by @id

Author: vorburger

docs/use/canonicalize/index.md

@@ -16,9 +16,9 @@
     limitations under the License.
 -->
 
-# Canonicalize
+# Canonicalize (AKA Normalize)
 
-_Canonicalization_ transforms a resource into a "standard" representation.
+_Canonicalization,_ which is also called _normalization,_ transforms a resource into a "standard" representation.
 
 This process is dependent on the type of the resource, but typically includes things such as:
 
@@ -27,7 +27,7 @@ This process is dependent on the type of the resource, but typically includes th
 * Rewriting literal values
 * Fixed Encoding
 
-This is sometimes useful e.g. when testing, to compare output to a fixed expected outcome.
+This is useful e.g. when testing, to compare output to a fixed expected outcome.
 
 It also has an application in [cryptography](https://github.com/enola-dev/enola/issues/284), and is useful when _"signing"_ things.
 
@@ -54,3 +54,24 @@ $ ./enola canonicalize --pretty --load=file:test/canonicalize.json
 ```
 
 Note how the order of the keys in the JSON changes, among other changes.
+
+## JSON-LD
+
+`enola canonicalize` for JSON-LD transforms this `canonicalize.jsonld`:
+
+```json
+{% include "../../../test/canonicalize.jsonld" %}
+```
+
+```bash cd ../.././..
+$ ./enola canonicalize --pretty --load=file:test/canonicalize.jsonld --output=file:test/canonicalize.jsonld.expected
+...
+```
+
+into this - note how the 🎨 painters' order was swapped, because not just all map keys but the list itself was also ordered alphabetically by `@id`:
+
+```json
+{% include "../../../test/canonicalize.jsonld.expected" %}
+```
+
+Future versions may implement full [RDF Dataset Canonicalization](https://www.w3.org/TR/rdf-canon/).

java/dev/enola/cli/CanonicalizeCommand.java

@@ -32,7 +32,7 @@
 @CommandLine.Command(
         name = "canonicalize",
         description = {
-            "Canonicalize Resources",
+            "Canonicalize (AKA normalize) resources",
             "using e.g. RFC 8785 JSON Canonicalization Scheme (JCS) inspired approach",
             "(but this implementation is currently not yet fully compliant with that RFC)"
         })

java/dev/enola/common/canonicalize/Canonicalizer.java

@@ -33,6 +33,8 @@
 
 public class Canonicalizer implements ResourceConverter {
 
+    // TODO Implement https://www.w3.org/TR/rdf-canon/
+
     public static final String PRETTY_QUERY_PARAMETER = "pretty";
 
     public static void canonicalize(ReadableResource in, WritableResource out, boolean pretty)

java/dev/enola/common/canonicalize/CanonicalizerTest.java

@@ -76,11 +76,22 @@ public void canonicalJSON_is_UTF8() throws IOException {
 
     @Test
     public void rfc8785() throws IOException {
-        var in = new ClasspathResource("canonicalize.json", MediaType.JSON_UTF_8);
+        var in = new ClasspathResource("canonicalize.json");
         var out = new MemoryResource(MediaType.JSON_UTF_8);
         Canonicalizer.canonicalize(in, out, false);
 
         var expected = new ClasspathResource("canonicalize.json.expected", MediaType.JSON_UTF_8);
         assertThat(out.charSource().read()).isEqualTo(expected.charSource().read());
     }
+
+    @Test
+    public void jsonld() throws IOException {
+        var md = MediaType.parse("application/ld+json").withCharset(UTF_8);
+        var in = new ClasspathResource("canonicalize.jsonld", md);
+        var out = new MemoryResource(MediaType.JSON_UTF_8);
+        Canonicalizer.canonicalize(in, out, true);
+
+        var expected = new ClasspathResource("canonicalize.jsonld.expected", MediaType.JSON_UTF_8);
+        assertThat(out.charSource().read()).isEqualTo(expected.charSource().read());
+    }
 }

java/dev/enola/common/yamljson/JSON.java

@@ -58,6 +58,8 @@ public static String write(Object root, boolean format) {
      */
     @SuppressWarnings("rawtypes")
     public static String canonicalize(String json, boolean format) {
+        // TODO Consider instead using
+        // https://github.com/filip26/titanium-json-ld/blob/5c2c02c1f65b8e885fb689a460efba3f6925b479/src/main/java/com/apicatalog/jsonld/json/JsonCanonicalizer.java#L39
         return write(sortByKeyIfMap(readObject(json)), format);
     }
 
@@ -73,6 +75,8 @@ private static Object sortByKeyIfMap(Object object) {
                 var sorted = sortByKeyIfMap(element);
                 newList.add(sorted);
             }
+            // TODO Do this only when canonicalizing JSON-LD, not any JSON:
+            sortListByID(newList);
             return newList;
         }
         return object;
@@ -89,5 +93,21 @@ private static Map<String, Object> sortByKey(Map<String, Object> map) {
         return newMap.build();
     }
 
+    private static void sortListByID(List<Object> list) {
+        Collections.sort(
+                list,
+                (o1, o2) -> {
+                    // skipcq: JAVA-C1003
+                    if (o1 instanceof Map m1 && o2 instanceof Map m2) {
+                        var oid1 = m1.get("@id");
+                        var oid2 = m2.get("@id");
+                        // skipcq: JAVA-C1003
+                        if (oid1 instanceof String id1 && oid2 instanceof String id2)
+                            return id1.compareTo(id2);
+                        return 0;
+                    } else return 0;
+                });
+    }
+
     private JSON() {}
 }

test/canonicalize.jsonld

@@ -0,0 +1,18 @@
+[
+  {
+    "@id": "http://example.enola.dev/Picasso",
+    "https://schema.org/name": [
+      {
+        "@value": "Pablo Picasso"
+      }
+    ]
+  },
+  {
+    "https://schema.org/name": [
+      {
+        "@value": "Salvador Domingo Felipe Jacinto Dalí"
+      }
+    ],
+    "@id": "http://example.enola.dev/Dalí"
+  }
+]

test/canonicalize.jsonld.expected

@@ -0,0 +1,18 @@
+[
+  {
+    "@id": "http://example.enola.dev/Dalí",
+    "https://schema.org/name": [
+      {
+        "@value": "Salvador Domingo Felipe Jacinto Dalí"
+      }
+    ]
+  },
+  {
+    "@id": "http://example.enola.dev/Picasso",
+    "https://schema.org/name": [
+      {
+        "@value": "Pablo Picasso"
+      }
+    ]
+  }
+]