Merge pull request #140 from filip26/feat/v1-decoder

V1.0 decoder + URIs

Author: filip26

README.md

@@ -6,8 +6,6 @@
 
 Iridium CBOR-LD is a Java implementation of [CBOR-LD 1.0](https://json-ld.github.io/cbor-ld-spec/), a compact binary format for Linked Data.
 
----
-
 ## ✨ Features
 
 - 🔄 Semantic compression and decompression
@@ -35,19 +33,14 @@ Iridium CBOR-LD is a Java implementation of [CBOR-LD 1.0](https://json-ld.github
 ```javascript
 // create an encoder builder initialized with default values
 var encoder = CborLd.createEncoder()
+               // terms dictionary (optional)
+               .dictionary(dictionary)
                // use bundled static contexts (true by default)
                .useBundledContexts(true)
                // loader (optional)
                .loader(...)
-               // custom terms dictionary (optional)
-               .dictionary(customDictionary)
                // create a new encoder instance
                .build(); 
-                   
-// create barcodes encoder builder 
-var encoder = CborLd.createEncoder(BarcodesConfig.INSTANCE)
-               // ... customize
-               .build()
 
 // encode a document
 byte[] encoded = encoder.encode(document);
@@ -58,37 +51,82 @@ byte[] encoded = encoder.encode(document);
 ```javascript
 // create a decoder builder initialized with default values
 var decoder = CborLd.createDecoder()
+               // terms dictionaries (optional)
+               .dictionary(dictionary1);
+               .dictionary(dictionary2);               
+               // ...
                // use bundled static contexts (true by default)
                .useBundledContexts(true)
                // loader (optional)
                .loader(...)
-               // add custom terms dictionary (optional)
-               .dictionary(customDictionary);
                // create a new decoder instance
                .build(); 
-                   
-// create barcodes decoder builder
-var decoder = CborLd.createDecoder(BarcodesConfig.INSTANCE)
-               // ... customize
-               .build()
-  
+
 // decode
 document = decoder.decode(encoded);
 ```
 
+### Dictionary
+
+It’s highly recommended to use dictionaries to maximize the compression ratio. A dictionary consists of terms and the codes they are encoded to. The dictionary code is preserved in the encoded CBOR-LD, but the decoder must have the same dictionary enabled. See the [W3C CBOR-LD Registry for examples](https://json-ld.github.io/cbor-ld-spec/#registry).
+
+A dictionary should contain terms that are not present in contexts, such as the context URIs themselves, custom common values bound to types, and custom common URIs.
+
+```javascript
+// build a new dictionary
+var dictionary = DocumentDictionaryBuilder
+            .create(DICTIONARY_CODE)
+            .context("https://www.w3.org/ns/credentials/v2", 1)
+            .context("https://w3id.org/vc-barcodes/v1", 2)
+            .type("https://w3id.org/security#cryptosuiteString",
+                    DictionaryBuilder.create()
+                            .set("ecdsa-rdfc-2019", 1)
+                            .set("ecdsa-sd-2023", 2)
+                            .set("eddsa-rdfc-2022", 3)
+                            .set("ecdsa-xi-2023", 4))
+            .uri("did:key:zDnaeWjKfs1ob9QcgasjYSPEMkwq31hmvSAWPVAgnrt1e9GKj", 1)
+            .uri("did:key:zDnaeWjKfs1ob9QcgasjYSPEMkwq31hmvSAWPVAgnrt1e9GKj#zDnaeWjKfs1ob9QcgasjYSPEMkwq31hmvSAWPVAgnrt1e9GKj", 2)            
+            .uri("https://sandbox.platform.veres.dev/statuses/z19rJ4oGrbFCqf3cNTVDHSbNd/status-lists", 3)
+            .uri("did:key:zDnaeZSD9XcuULaS8qmgDUa6TMg2QjF9xABnZK42awDH3BEzj", 4)
+            .build();
+
+// use with encoder
+var encoder = CborLd.createEncoder()
+                .dictionary(dictionary)
+                .loader(...)
+                // customize
+                .build();
+
+// use with decoder, please note you can register multiple dictionaries
+var decoder = CborLd.createDecoder()
+                .dictionary(dictionary)
+                .loader(...)
+                // customize
+                .build();
+               
+```
+
 ### Backward Compatibility
 
 ```javascript
-// Iridium < v0.2.0
-CborLd.create[Encoder|Decoder](V05Config.INSTANCE)
+// CBOR-LD v0.5
+CborLd.createEncoder(CborLdVersion.V05)
       // ... customize      
       .build();
-      
-// Iridium < v0.2.0, @digitalbazaar/cborld compatibility
-CborLd.create[Encoder|Decoder](V05Config.INSTANCE)
-      .compactArrays(false)
+
+// CBOR-LD v0.6
+CborLd.createEncoder(CborLdVersion.V06)
       // ... customize      
       .build();
+
+// Multi-Decoder 
+CborLd.createDecoder(CborLdVersion.V1, CborLdVersion.V06, CborLdVersion.V05)
+      // sets dictionary for v1
+      .dictionary(dictionary)
+      // sets dictionary for v0.6
+      .dictionary(CborLdVersion.V06, dictionary)
+      // ... customize
+      .build();      
 ```
 
 

src/main/java/com/apicatalog/cborld/config/ConfigV1.java

@@ -23,7 +23,6 @@
 import com.apicatalog.cborld.encoder.EncoderConfig;
 import com.apicatalog.cborld.encoder.value.ContextValueEncoder;
 import com.apicatalog.cborld.encoder.value.CustomTypeValueEncoder;
-import com.apicatalog.cborld.encoder.value.CustomUriValueEncoder;
 import com.apicatalog.cborld.encoder.value.DidKeyValueEncoder;
 import com.apicatalog.cborld.encoder.value.IdValueEncoder;
 import com.apicatalog.cborld.encoder.value.MultibaseValueEncoder;
@@ -63,7 +62,6 @@ public class ConfigV1 extends BaseConfig implements EncoderConfig, DecoderConfig
         valueEncoders.add(new CustomTypeValueEncoder());
 
         // value driven
-        valueEncoders.add(new CustomUriValueEncoder());
         valueEncoders.add(new UuidValueEncoder());
         valueEncoders.add(new DidKeyValueEncoder());
 

src/main/java/com/apicatalog/cborld/decoder/DecoderV1.java

@@ -13,6 +13,7 @@
 
 import co.nstant.in.cbor.CborDecoder;
 import co.nstant.in.cbor.CborException;
+import co.nstant.in.cbor.model.Array;
 import co.nstant.in.cbor.model.DataItem;
 import co.nstant.in.cbor.model.MajorType;
 import co.nstant.in.cbor.model.UnsignedInteger;
@@ -30,11 +31,21 @@ public JsonValue decode(CborLdVersion version, byte[] encoded) throws ContextErr
             final ByteArrayInputStream bais = new ByteArrayInputStream(encoded);
             final List<DataItem> dataItems = new CborDecoder(bais).decode();
 
-            if (dataItems.size() != 2) {
+            if (dataItems.size() != 1) {
+                throw new DecoderError(Code.InvalidDocument, "The document is not CBOR-LD v1.0 document.");                
+            }
+
+            final DataItem dataItem = dataItems.iterator().next();
+            
+            if (dataItem == null || dataItem.getMajorType() != MajorType.ARRAY) {
+                throw new DecoderError(Code.InvalidDocument, "The document is not CBOR-LD v1.0 document. Must start with array of two items, but is " + dataItem + ".");
+            }
+            
+            if (((Array)dataItem).getDataItems().size() != 2) {
                 throw new DecoderError(Code.InvalidDocument, "The document is not CBOR-LD v1.0 document. Must start with array of two items but size = " + dataItems.size() + ".");
             }
 
-            final Iterator<DataItem> it = dataItems.iterator();
+            final Iterator<DataItem> it = ((Array)dataItem).getDataItems().iterator();
 
             final DataItem registryId = it.next();
 

src/main/java/com/apicatalog/cborld/decoder/value/IdValueDecoder.java

@@ -18,10 +18,16 @@ public class IdValueDecoder implements ValueDecoder {
     public JsonValue decode(Mapping mapping, DataItem value, String term, Collection<String> types) throws DecoderError {
         if (mapping != null && mapping.terms() != null && types != null && types.contains(Keywords.ID)
                 && MajorType.UNSIGNED_INTEGER.equals(value.getMajorType())) {
-            final String type = mapping.terms().getValue(((UnsignedInteger) value).getValue().intValueExact());
-
-            if (type != null) {
-                return Json.createValue(type);
+            
+            int code = ((UnsignedInteger) value).getValue().intValueExact();
+            
+            String id = mapping.uris().getValue(code);
+            if (id == null) {
+                id = mapping.terms().getValue(code);
+            }
+            
+            if (id != null) {
+                return Json.createValue(id);
             }
         }
         return null;

src/main/java/com/apicatalog/cborld/encoder/value/IdValueEncoder.java

@@ -14,10 +14,15 @@ public class IdValueEncoder implements ValueEncoder {
 
     @Override
     public DataItem encode(Mapping mapping, JsonValue jsonValue, String term, Collection<String> types) {
-
         if (types != null && types.contains(Keywords.ID)) {
 
-            final Integer code = mapping.terms().getCode(((JsonString) jsonValue).getString());
+            final String id = ((JsonString) jsonValue).getString();
+
+            Integer code = mapping.uris().getCode(id);
+
+            if (code == null) {
+                code = mapping.terms().getCode(id);
+            }
 
             if (code != null) {
                 return new UnsignedInteger(code);

src/test/resources/com/apicatalog/cborld/decoder-manifest.jsonld

@@ -332,6 +332,46 @@
       "name": "0.6: Utopia EAD VCB",
       "input": "0.6/barcode-ex-14.cborld",
       "expect": "0.6/barcode-ex-14.jsonld" 
+    },
+    {
+        "@id": "#t0200",
+        "@type": [
+        "PositiveEvaluationTest",
+        "DecoderTest"
+        ],
+        "name": "1.0: Utopia Driver's License VCB",
+        "input": "1.0/utopia-12.cborld",
+        "expect": "1.0/utopia-12.jsonld"
+    },
+    {
+        "@id": "#t0201",
+        "@type": [
+          "PositiveEvaluationTest",
+          "DecoderTest"
+        ],
+        "name": "1.0: Utopia EAD VCB",
+        "input": "1.0/utopia-19.cborld",
+        "expect": "1.0/utopia-19.jsonld" 
+    },
+    {
+        "@id": "#t0202",
+        "@type": [
+        "PositiveEvaluationTest",
+        "DecoderTest"
+        ],
+        "name": "1.0: URIs: Utopia Driver's License VCB",
+        "input": "1.0/utopia-ext-12.cborld",
+        "expect": "1.0/utopia-ext-12.jsonld"
+    },
+    {
+        "@id": "#t0201",
+        "@type": [
+          "PositiveEvaluationTest",
+          "DecoderTest"
+        ],
+        "name": "1.0: URIs: Utopia EAD VCB",
+        "input": "1.0/utopia-ext-19.cborld",
+        "expect": "1.0/utopia-ext-19.jsonld" 
     }
   ]
 }