This document defines the production and consumption rules for a CBOR representation for DID Documents [DID-CORE].
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.
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 firstname.lastname@example.org ( subscribe, archives).
This document was published by the Decentralized Identifier Working Group as a First Public 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 email@example.com (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.
This document is governed by the 15 September 2020 W3C Process Document.
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.
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.
This section defines the production and consumption rules for a CBOR representation for DID Documents.
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.|
A CBOR string (major type 3) formatted as
an XML Datetime normalized to
UTC 00:00 and without sub-second decimal precision. For example:
|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:
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:
A2626964781E6469643A6578616D706C653A313233343536373839616263 6465666768696E61757468656E7469636174696F6E81A462696478256469 643A6578616D706C653A313233343536373839616263646566676869236B 6579732D316474797065781A45643235353139566572696669636174696F 6E4B6579323031386A636F6E74726F6C6C6572781E6469643A6578616D70 6C653A3132333435363738396162636465666768696F7075626C69634B65 79426173653538782C483343324156764C4D7636676D4D4E616D33755641 6A5A70666B634A437744776E5A6E367A3377586D715056
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"
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:
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.
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.
Fragment identifiers used with
application/did+cbor are treated
according to the rules defined in Decentralized Identifiers (DIDs) v1.0.