w3c / did-cbor-note

WG Note on DID CBOR Representation

The application/did+cbor Representation

This is the repository of the W3C’s specification on a DID Document Representation for CBOR, developed by the DID Working Group. The editors’ draft of the specification can also be read directly.

Contributing to the Repository

Use the standard fork, branch, and pull request workflow to propose changes to the specification. Please make branch names informative—by including the issue or bug number for example.

Editorial changes that improve the readability of the spec or correct spelling or grammatical mistakes are welcome.

Please read CONTRIBUTING.md, about licensing contributions.

Code of Conduct

W3C functions under a code of conduct.

DID Working Group Repositories

• W3C Decentralized Identifier Specification v1.0
• Home page of the Decentralized Identifier Working Group
• Specs and documentation for all DID-related /.well-known resources
• W3C Decentralized Characteristics Rubric v1.0
• Decentralized Identifier Use Cases v1.0
• W3C DID Test Suite and Implementation Report

did-cbor-note's Issues

Title of document is misleading

From w3c/transitions#348 (comment) ...

@tidoust wrote: I note that the title of the spec is a bit misleading without context. I initially thought that this was about CBOR itself, which surprised me, not about CBOR usage for DID documents. May I suggest to consider renaming the spec slightly e.g. to include "for DID documents" in the title? I do realize it appears in the subtitle, but subtitles are rarely included.

Change the title of the specification to address @tidoust's concern.

The abstract should not say 'section'

At present, it says

This section defines the production and consumption rules for a CBOR representation for DID Documents [DID-CORE].

It should say 'document'

Disagreement on recommending implementation of application/did+cbor

There continues to be a disagreement on whether or not implementers should implement the application/did+cbor media type. The specification needs to mention this since it was a topic of many debates in the DID WG. Implementers should know that not all WG members felt that application/did+cbor was an appropriate use of CBOR.

Yes, it's easy to implement because it's just a translation of JSON -> CBOR -- but that's really it's key use. As an exemplar for easy implementation, not as an encoding that takes advantage of many of the features that others have come to expect with CBOR. Namely, it doesn't provide the sorts of storage savings that many CBOR representations do.

All of this needs to be called out in the NOTE that is published.

Title of the document...

At present, it says "application/did+cbor v1.0". Besides being unusual, I am not even sure it would not create problem to have it in our TR collection...

I would propose something more human readable:-)

CBOR tag assignment

The CBOR DID document should have a CBOR tag assignment from the IANA CBOR registry: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml

Given an assigned CBOR tag, say #6.4711, a tagged-did definition might be:

tagged-did = $6.4711(bytes .cbor did-map)

Where did-map is a did document.

The use case for this is CBOR documents that include a DID document would prefer to use CBOR tagging vs. media-type.

Q: Is there a CDDL definition of a DID document? It would be extreemely helpful to reference it from the CBOR Representation specification: https://www.w3.org/TR/did-cbor-representation/

Deterministic CBOR (CDE) and Determinism with Numeric Reduction (dCBOR)

For cryptographic signatures, determinism is essential. The purpose of determinism is to ensure that semantically equivalent data items are encoded into identical byte streams. The IETF CBOR spec RFC-8949 has a section on determinism (§4.2), however, it is underspecified.

In the last year there are two documents advancing to address this underspecification, and there are also libraries in a number of languages that support one or both.

The base document is CBOR Common Deterministic Encoding (CDE) which cleans up those §4.2 issues. It also describe how §3 Application Profiles function.

At this point, there is only one Application Profile, which is dCBOR, which adds Numeric Reduction, and is slightly more restrictive then CDE. Numeric reduction further ensures that semantically equal numeric values (e.g. 2 and 2.0) are encoded into identical byte streams (e.g. 0x02) by encoding "Integral floating point values" (floating point values with a zero fractional part) as integers when possible. This also means that the three representations of a zero number in CBOR (0, 0.0, -0.0 in diagnostic notation) are all reduced to the basic integer 0 (with preferred encoding 0x00).

There are some other sharp edges in the dCBOR I-D that are restricted, such as requiring lexicographic ordering of map keys such as maps must not have duplicate keys, restricts various NAN values. dCBOR also doesn't support bigint.

There are more details on dCBOR at https://developer.blockchaincommons.com/dcbor/ and there are now multiple libraries in multiple languages that support it, including Rust, Typescript, Ruby, and Swift. I have heard that there are more now that support dCBOR, including Java, but I've not validated them.

Both of these deterministic CBOR documents are have been adopted by the CBOR-WG and are relatively mature, and are on different RFC tracks.

I am one of the co-authors of the dCBOR I-D, which inspired the CDE document. Our reasoning for support for numeric reduction is address many of the problems across different languages at a lower level than the semantic layer. You don't need a schema to order maps and validate numbers — schemas instead can focus the semantic layer, rather than the data layer. We leverage this with great utility in our higher level structured data model, triple store, and Merkle tree based Gordian Envelope I-D (more details and code).

I'd like to suggest that this document leverage the CDE/dCBOR drafts and conform with them for determinism. If there is some reason they can't, let the CBOR community know, or consider creating your own Application Profile with your determinism rules.