The Plain CBOR Representation v1.0

Expressing a DID Document using the application/did+cbor media type

W3C Working Group Note

This version:
https://www.w3.org/TR/2021/NOTE-did-cbor-representation-20210629/
Latest published version:
https://www.w3.org/TR/did-cbor-representation/
Latest editor's draft:
https://w3c.github.io/did-cbor-note/
Editors:
Jonathan Holt (TranSendX)
Manu Sporny (Digital Bazaar)
Author:
Jonathan Holt (TranSendX)
Participate:
GitHub w3c/did-cbor-note
File an issue
Commit history
Pull requests

Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

Abstract

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

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The W3C Decentralized Identifier Working Group has published this document as a W3C NOTE and is requesting that software developers provide experimental implementations designed to test the implementability of all of the features in this document.

Note: Debate related to purpose of format

The W3C Decentralized Identifier Working Group attempted to normatively define the content in this document in the [DID-CORE] specification. A lack of implementations and tests resulted in the removal of the application/did+cbor representation from [DID-CORE] and the publication of that content in this document. There remains an unresolved debate related to whether or not this representation is appropriate for broad implementation. Other, more compact CBOR representations that take advantage of the compactness of data format might be a better fit for a variety of use cases.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-did-wg@w3.org ( subscribe, archives).

This document was published by the Decentralized Identifier Working Group as a Working Group Note.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-did-wg@w3.org (subscribe, archives).

Publication as a Working Group Note does not imply endorsement by the W3C Membership.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 15 September 2020 W3C Process Document.

1. Introduction

This section is non-normative.

The Decentralized Identifier specification [DID-CORE] defines a data model that can be expressed in a variety of representation formats. This document specifies the production rules for converting the DID document data model to a plain CBOR representation as well as the consumption rules for taking a plain CBOR DID document representation and converting that back into the DID document data model.

Readers are advised to familiarize themselves with the Decentralized Identifier specification [DID-CORE] before reading the rest of the content in this document.

1.1 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY and MUST in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. The Plain CBOR Representation

This section defines the production and consumption rules for a CBOR representation for DID Documents.

2.1 Production

The DID document, DID document data structures, and representation-specific entries map MUST be serialized to the CBOR representation according to the following production rules:

Data Type CBOR Representation Type
map A CBOR map (major type 5), where each entry is represented as a member of the CBOR map. The entry key is expressed as a CBOR string (major type 3) as the key, and the entry value according to its type, as defined in this table.
list A CBOR array (major type 4), where each element of the list is added, in order, as a value of the array according to its type, as defined in this table.
set A CBOR array (major type 4), where each element of the list is added, in order, as a value of the array according to its type, as defined in this table.
datetime A CBOR string (major type 3) formatted as an XML Datetime normalized to UTC 00:00 and without sub-second decimal precision. For example: 2020-12-20T19:17:47Z.
string A CBOR string (major type 3).
integer A CBOR integer (major type 0 or 1), choosing the shortest byte representation.
double A CBOR floating-point number (major type 7). All floating point values MUST be encoded as 64-bits (additional type value 27), even for integral values.
boolean A CBOR simple value (major type 7, subtype 24) with a simple value of 21 (true) or 20 (false).
null A CBOR simple value (major type 7, subtype 24) with a simple value of 22 (null).

In addition to the data type production rules above, the following rules apply for conforming producers that serialize CBOR representations:

  1. Indefinite-length items are not allowed and MUST be made a CBOR definite length.
  2. All CBOR tags MUST be retained regardless of whether they are optional.
  3. All four Canonical CBOR rules listed in [RFC8949] MUST be applied to all relevant data types.

All entries of a DID document MUST be included in the root CBOR map (major type 5). Entries MAY contain additional data substructures subject to the value representation rules in the list above. When serializing a DID document to its CBOR representation, a conforming producer MUST specify a media type of application/did+cbor to downstream applications such as described in the section on DID Resolution Metadata.

The following examples express the CBOR representation of a DID document in hexidecimal notation, and in CBOR diagnostic notation:

Example 1: DID Document encoded as CBOR (hexadecimal) 
A2626964781E6469643A6578616D706C653A313233343536373839616263
6465666768696E61757468656E7469636174696F6E81A462696478256469
643A6578616D706C653A313233343536373839616263646566676869236B
6579732D316474797065781A45643235353139566572696669636174696F
6E4B6579323031386A636F6E74726F6C6C6572781E6469643A6578616D70
6C653A3132333435363738396162636465666768696F7075626C69634B65
79426173653538782C483343324156764C4D7636676D4D4E616D33755641
6A5A70666B634A437744776E5A6E367A3377586D715056
Example 2: DID Document encoded as CBOR (diagnostic notation) 
A2                                   # map(2)
62                                   # text(2)
   6964                              # "id"
78 1E                                # text(30)
   6469643A6578616D706C653A313233343536373839616263646566676869 # "did:example:123456789abcdefghi"
6E                                   # text(14)
   61757468656E7469636174696F6E      # "authentication"
81                                   # array(1)
   A4                                # map(4)
      62                             # text(2)
         6964                        # "id"
      78 25                          # text(37)
         6469643A6578616D706C653A313233343536373839616263646566676869236B6579732D31 # "did:example:123456789abcdefghi#keys-1"
      64                             # text(4)
         74797065                    # "type"
      78 1A                          # text(26)
         45643235353139566572696669636174696F6E4B657932303138 # "Ed25519VerificationKey2020"
      6A                             # text(10)
         636F6E74726F6C6C6572        # "controller"
      78 1E                          # text(30)
         6469643A6578616D706C653A313233343536373839616263646566676869 # "did:example:123456789abcdefghi"
      6F                             # text(15)
         7075626C69634B6579426173653538 # "publicKeyMultibase"
      78 2C                          # text(44)
         483343324156764C4D7636676D4D4E616D337556416A5A70666B634A437744776E5A6E367A3377586D715056 # "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"

2.2 Consumption

The DID document and any DID document data structures expressed by the data model MUST be deserialized into the data model according to the following consumption rules:

CBOR Representation Type Data Type
CBOR map (major type 5) A map, where each data item of the CBOR map is added as an entry to the map with the entry key being the data item name and the value converted based on the CBOR type and, if available, entry definition, as defined here; as no order can be enforced for general CBOR maps, no insertion order is guaranteed.
CBOR array (major type 4), where the data model entry value is a list or unknown A list, where each value of the CBOR array is added to the list in order, converted based on the CBOR type of the array value, as defined in this table.
CBOR array (major type 4), where the data model entry value is a set A set, where each value of the CBOR array is added to the set in order, converted based on the CBOR type of the array value as defined in this table.
CBOR string (major type 3) where the data model entry value is a datetime A datetime.
CBOR string (major type 3), where the data model entry value type is string or unknown. A string.
CBOR integer (major type 0 or 1), choosing the shortest byte representation An integer.
CBOR floating-point number (major type 7) A double.
CBOR simple value (major type 7, subtype 24) with a simple value of 21 (True) or 20 (False) A boolean.
CBOR simple value (major type 7, subtype 24) with a simple value of 22 (Null) A null value.

In addition to the data type consumption rules above, the following rules apply for conforming consumers that deserialize CBOR conforming consumers that deserialize CBOR representations:

  1. CBOR indefinite-length items are not allowed and MUST produce an error.
  2. A duplicate key in the same CBOR map MUST produce an error.
  3. All CBOR tags MUST be retained for CBOR production regardless of whether they are optional.

If media type information is available to a conforming consumer and the media type value is application/did+cbor, then the data structure being consumed is a DID document, and the root element MUST be a CBOR map (major type 5) where all members of the object are entries of the DID document. A conforming consumer for a CBOR representation that is consuming a DID document with a root element that is not a CBOR map (major type 5) MUST report an error.

A. IANA Considerations

This section will be submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA if this specification becomes a W3C Proposed Recommendation.

A.1 application/did+cbor

Type name:
application
Subtype name:
did+cbor
Required parameters:
None
Optional parameters:
None
Encoding considerations:
See RFC 8949, section 4.2.1.
Security considerations:
See RFC 8949, section 10 [RFC8949].
Interoperability considerations:
Not Applicable
Published specification:
http://www.w3.org/TR/did-core/
Applications that use this media type:
Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.didcbor
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Ivan Herman <ivan@w3.org>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
Change controller:
W3C

Fragment identifiers used with application/did+cbor are treated according to the rules defined in Decentralized Identifiers (DIDs) v1.0.

B. References

B.1 Normative references

[DID-CORE]
Decentralized Identifiers (DIDs) v1.0. Drummond Reed; Manu Sporny; Markus Sabadello; Dave Longley; Christopher Allen. W3C. 15 May 2021. W3C Candidate Recommendation. URL: https://www.w3.org/TR/did-core/
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[RFC8949]
Concise Binary Object Representation (CBOR). C. Bormann; P. Hoffman. IETF. December 2020. Internet Standard. URL: https://tools.ietf.org/html/rfc8949
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/