W3C
Candidate
Recommendation
Snapshot
08
Copyright © 2025 World Wide Web Consortium . W3C ® liability , trademark and permissive document license rules apply.
Decentralized identifiers (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. A DID refers to any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) as determined by the controller of the DID . In contrast to typical, federated identifiers, DIDs have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, while other parties might be used to help enable the discovery of information related to a DID , the design enables the controller of a DID to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID subject with a DID document allowing trustable interactions associated with that subject.
Each DID document can express cryptographic material, verification methods , or services , which provide a set of mechanisms enabling a DID controller to prove control of the DID . Services enable trusted interactions associated with the DID subject . A DID might provide the means to return the DID subject itself, if the DID subject is an information resource such as a data model.
This document specifies the DID syntax, a common data model, core properties, serialized representations, DID operations, and an explanation of the process of resolving DIDs to the resources that they represent.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index .
This version of the DID Core specification, version 1.1, is experimental. DO NOT implement it. If you want to implement DIDs, use the current version 1.0 specification: Decentralized Identifiers (DIDs) v1.0 .
This document was published by the Decentralized Identifier Working Group as a Candidate Recommendation Snapshot using the Recommendation track .
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Snapshot has received wide review , is intended to gather implementation experience , and has commitments from Working Group members to royalty-free licensing for implementations.
This Candidate Recommendation is not expected to advance to Proposed Recommendation any earlier than 30 January 2026.
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 that 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 18 August 2025 W3C Process Document .
This section is non-normative.
As individuals and organizations, many of us use globally unique identifiers in a wide variety of contexts. They serve as communications addresses (telephone numbers, email addresses, usernames on social media), ID numbers (for passports, drivers licenses, tax IDs, health insurance), and product identifiers (serial numbers, barcodes, RFIDs). URIs (Uniform Resource Identifiers) are used for resources on the Web and each web page you view in a browser has a globally unique URL (Uniform Resource Locator).
The vast majority of these globally unique identifiers are not under our control. They are issued by external authorities that decide who or what they refer to and when they can be revoked. They are useful only in certain contexts and recognized only by certain bodies not of our choosing. They might disappear or cease to be valid with the failure of an organization. They might unnecessarily reveal personal information. In many cases, they can be fraudulently replicated and asserted by a malicious third-party, which is more commonly known as "identity theft".
The Decentralized Identifiers (DIDs) defined in this specification are a new type of globally unique identifier. They are designed to enable individuals and organizations to generate their own identifiers using systems they trust. These new identifiers enable entities to prove control over them by authenticating using cryptographic proofs such as digital signatures.
Since the generation and assertion of Decentralized Identifiers is entity-controlled, each entity can have as many DIDs as necessary to maintain their desired separation of identities, personas, and interactions. The use of these identifiers can be scoped appropriately to different contexts. They support interactions with other people, institutions, or systems that require entities to identify themselves, or things they control, while providing control over how much personal or private data should be revealed, all without depending on a central authority to guarantee the continued existence of the identifier. These ideas are explored in the DID Use Cases document [ DID-USE-CASES ].
This specification does not presuppose any particular technology or cryptography to underpin the generation, persistence, resolution, or interpretation of DIDs. For example, implementers can create Decentralized Identifiers based on identifiers registered in federated or centralized identity management systems. Indeed, almost all types of identifier systems can add support for DIDs. This creates an interoperability bridge between the worlds of centralized, federated, and decentralized identifiers. This also enables implementers to design specific types of DIDs to work with the computing infrastructure they trust, such as distributed ledgers, decentralized file systems, distributed databases, and peer-to-peer networks.
This specification is for:
In addition to this specification, readers might find the Use Cases and Requirements for Decentralized Identifiers [ DID-USE-CASES ] document useful.
This section is non-normative.
A
DID
is
a
simple
text
string
consisting
of
three
parts:
1)
the
did
URI
scheme
identifier,
2)
the
identifier
for
the
DID
method
,
and
3)
the
DID
method-specific
identifier.
The example DID above resolves to a DID document . A DID document contains information associated with the DID , such as ways to cryptographically authenticate a DID controller .
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123456789abcdefghi",
"authentication": [{
// used to authenticate as did:...fghi
"id": "did:example:123456789abcdefghi#keys-1",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}]
}
This section is non-normative.
Decentralized Identifiers are a component of larger systems, such as the Verifiable Credentials ecosystem [ VC-DATA-MODEL ], which influenced the design goals for this specification. The design goals for Decentralized Identifiers are summarized here.
| Goal | Description |
|---|---|
| Decentralization | Eliminate the requirement for centralized authorities or single points of failure in identifier management, including the registration of globally unique identifiers, public verification keys, services , and other information. |
| Control | Give entities, both human and non-human, the power to directly control their digital identifiers without the need to rely on external authorities. |
| Privacy | Enable entities to control the privacy of their information, including minimal, selective, and progressive disclosure of attributes or other data. |
| Security | Enable sufficient security for requesting parties to depend on DID documents for their required level of assurance. |
| Proof-based | Enable DID controllers to provide cryptographic proof when interacting with other entities. |
| Discoverability | Make it possible for entities to discover DIDs for other entities, to learn more about or interact with those entities. |
| Interoperability | Use interoperable standards so DID infrastructure can make use of existing tools and software libraries designed for interoperability. |
| Portability | Be system- and network-independent and enable entities to use their digital identifiers with any system that supports DIDs and DID methods . |
| Simplicity | Favor a reduced set of simple features to make the technology easier to understand, implement, and deploy. |
| Extensibility | Where possible, enable extensibility provided it does not greatly hinder interoperability, portability, or simplicity. |
This section is non-normative.
This section provides a basic overview of the major components of Decentralized Identifier architecture.
Six internally-labeled shapes appear in the diagram, with labeled arrows between them, as follows. In the center of the diagram is a rectangle labeled DID URL, containing small typewritten text "did:example:123/path/to/rsrc". At the center top of the diagram is a rectangle labeled, "DID", containing small typewritten text "did:example:123". At the top left of the diagram is an oval, labeled "DID Subject". At the bottom center of the diagram is a rectangle labeled, "DID document". At the bottom left is an oval, labeled, "DID Controller". On the center right of the diagram is a two-dimensional rendering of a cylinder, labeled, "Verifiable Data Registry".
From the top of the "DID URL" rectangle, an arrow, labeled "contains", extends upwards, pointing to the "DID" rectangle. From the bottom of the "DID URL" rectangle, an arrow, labeled "refers, and dereferences , to", extends downward, pointing to the "DID document" rectangle. An arrow from the "DID" rectangle, labeled " resolves to", points down to the "DID document" rectangle. An arrow from the "DID" rectangle, labeled "refers to", points left to the "DID subject" oval. An arrow from the "DID controller" oval, labeled "controls", points right to the "DID document" rectangle. An arrow from the "DID" rectangle, labeled "recorded on", points downards to the right, to the "Verifiable Data Registry" cylinder. An arrow from the "DID document" rectangle, labeled "recorded on", points upwards to the right to the "Verifiable Data Registry" cylinder.
did:
,
a
method
identifier,
and
a
unique,
method-specific
identifier
specified
by
the
DID
method
.
DIDs
are
resolvable
to
DID
documents
.
A
DID
URL
extends
the
syntax
of
a
basic
DID
to
incorporate
other
standard
URI
components
such
as
path,
query,
and
fragment
in
order
to
locate
a
particular
resource
—for
example,
a
cryptographic
public
key
inside
a
DID
document
,
or
a
resource
external
to
the
DID
document
.
These
concepts
are
elaborated
upon
in
3.1
DID
Syntax
and
3.2
DID
URL
Syntax
.
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 , MUST , MUST NOT , RECOMMENDED , SHOULD , and SHOULD NOT 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
document
contains
examples
that
contain
JSON
and
JSON-LD
content.
Some
of
these
examples
contain
characters
that
are
invalid,
such
as
inline
comments
(
//
)
and
the
use
of
ellipsis
(
...
)
to
denote
information
that
adds
little
value
to
the
example.
Implementers
are
cautioned
to
remove
this
content
if
they
desire
to
use
the
information
as
valid
JSON
or
JSON-LD.
Some
examples
contain
terms,
both
property
names
and
values,
that
are
not
defined
in
this
specification.
These
are
indicated
with
a
comment
(
//
external
(property
name|value)
).
Such
terms,
when
used
in
a
DID
document
,
are
expected
to
be
registered
in
the
repository
of
DID
Extensions
[
DID-EXTENSIONS
]
with
links
to
both
a
formal
definition
and
a
JSON-LD
context.
Interoperability of implementations for DIDs and DID documents is tested by evaluating an implementation's ability to create and parse DIDs and DID documents that conform to this specification. Interoperability for producers and consumers of DIDs and DID documents is provided by ensuring the DIDs and DID documents conform. Interoperability for DID method specifications is provided by the details in each DID method specification. It is understood that, in the same way that a web browser is not required to implement all known URI schemes, conformant software that works with DIDs is not required to implement all known DID methods . However, all implementations of a given DID method are expected to be interoperable for that method.
A conforming DID is any concrete expression of the rules specified in 3. Identifier which complies with relevant normative statements in that section.
A conforming DID document is any concrete expression of the data model described in this specification which complies with the relevant normative statements in 4. Data Model and 5. Core Properties . A serialization format for the conforming document is deterministic, bi-directional, and lossless, as described in 6. Representations .
A conforming producer is any algorithm realized as software and/or hardware that generates conforming DIDs or conforming DID Documents and complies with the relevant normative statements in 6. Representations .
A conforming consumer is any algorithm realized as software and/or hardware that consumes conforming DIDs or conforming DID documents and complies with the relevant normative statements in 6. Representations .
A conforming DID method is any specification that complies with the relevant normative statements in 7. Methods .
This section is non-normative.
This specification has two primary audiences: implementers of conformant DID methods; and implementers of systems and services that wish to interact and interface with DIDs. The intended audience includes, but is not limited to, software architects, data modelers, application developers, service developers, testers, operators, and user experience (UX) specialists. Other people involved in a broad range of standards efforts related to decentralized identity, verifiable credentials, and secure storage might also be interested in reading this specification.
This section is non-normative.
This section defines the terms used in this specification and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification.
controller
property
at
the
top
level
of
the
DID
document
.
Note
that
a
DID
controller
might
be
the
DID
subject
.
#
).
DID
fragment
syntax
is
identical
to
URI
fragment
syntax.
/
)
character
and
ends
with
either
a
question
mark
(
?
)
character,
a
fragment
hash
sign
(
#
)
character,
or
the
end
of
the
DID
URL
.
DID
path
syntax
is
identical
to
URI
path
syntax.
See
Path
.
?
).
DID
query
syntax
is
identical
to
URI
query
syntax.
See
Query
.
did:
as
defined
in
3.1
DID
Syntax
.
Each
DID
method
specification
defines
a
specific
DID
method
scheme
that
works
with
that
specific
DID
method
.
In
a
specific
DID
method
scheme,
the
DID
method
name
follows
the
first
colon
and
terminates
with
the
second
colon,
e.g.,
did:example:
/
character),
optional
DID
query
(with
its
leading
?
character),
and
optional
DID
fragment
(with
its
leading
#
character).
In addition to the terminology above, this specification also uses terminology from the [ INFRA ] specification to formally define the data model . When [ INFRA ] terminology is used, such as string , set , and map , it is linked directly to that specification.
This section describes the formal syntax for DIDs and DID URLs . The term "generic" is used to differentiate the syntax defined here from syntax defined by specific DID methods in their respective specifications. The creation processes, and their timing, for DIDs and DID URLs are described in 7.2 Method Operations and B.2 Creation of a DID .
The
generic
DID
scheme
is
a
URI
scheme
conformant
with
[
RFC3986
].
The
ABNF
definition
can
be
found
below,
which
uses
the
syntax
in
[
RFC5234
]
and
the
corresponding
definitions
for
ALPHA
and
DIGIT
.
All
other
rule
names
not
defined
in
the
ABNF
below
are
defined
in
[
RFC3986
].
All
DIDs
MUST
conform
to
the
DID
Syntax
ABNF
Rules.
| The DID Syntax ABNF Rules |
|---|
did = "did:" method-name ":" method-specific-id method-name = 1*method-char method-char = %x61-7A / DIGIT method-specific-id = *( *idchar ":" ) 1*idchar idchar = ALPHA / DIGIT / "." / "-" / "_" / pct-encoded pct-encoded = "%" HEXDIG HEXDIG |
For requirements on DID methods relating to the DID syntax, see Section 7.1 Method Syntax .
A DID URL is a network location identifier for a specific resource . It can be used to retrieve things like representations of DID subjects , verification methods , services , specific parts of a DID document , or other resources.
The
following
is
the
ABNF
definition
using
the
syntax
in
[
RFC5234
].
It
builds
on
the
did
scheme
defined
in
3.1
DID
Syntax
.
The
path-abempty
,
query
,
and
fragment
components
are
defined
in
[
RFC3986
].
All
DID
URLs
MUST
conform
to
the
DID
URL
Syntax
ABNF
Rules.
DID
methods
can
further
restrict
these
rules,
as
described
in
7.1
Method
Syntax
.
| The DID URL Syntax ABNF Rules |
|---|
did-url = did path-abempty [ "?" query ] [ "#" fragment ] |
Although
the
semicolon
(
;
)
character
can
be
used
according
to
the
rules
of
the
DID
URL
syntax,
future
versions
of
this
specification
may
use
it
as
a
sub-delimiter
for
parameters
as
described
in
[
MATRIX-URIS
].
To
avoid
future
conflicts,
developers
ought
to
refrain
from
using
it.
A
DID
path
is
identical
to
a
generic
URI
path
and
conforms
to
the
path-abempty
ABNF
rule
in
RFC 3986,
section
3.3
.
As
with
URIs
,
path
semantics
can
be
specified
by
DID
Methods
,
which
in
turn
might
enable
DID
controllers
to
further
specialize
those
semantics.
did:example:123456/path
A
DID
query
is
identical
to
a
generic
URI
query
and
conforms
to
the
query
ABNF
rule
in
RFC 3986,
section
3.4
.
did:example:123456?versionId=1
Implementers are urged to avoid comparing DID URLs for equivalence when they have more than one query parameter without a specification specifically designed for that purpose. This specification defines no normalization rules for query parameters, and any query parameter normalization rules defined at the DID Method specification or application layer are not universally recognized rules.
DID
fragment
syntax
and
semantics
are
identical
to
a
generic
URI
fragment
and
conforms
to
the
fragment
ABNF
rule
in
RFC 3986,
section
3.5
.
A DID fragment is used as a method-independent reference into a DID document or external resource . Some examples of DID fragment identifiers are shown below.
did:example:123#public-key-1
did:example:123#service-5
In order to maximize interoperability, implementers are urged to ensure that DID fragments are interpreted in the same way across representations (see 6. Representations ). For example, while JSON Pointer [ RFC6901 ] can be used in a DID fragment , it will not be interpreted in the same way across non-JSON representations .
Additional semantics for fragment identifiers, which are compatible with and layered upon the semantics in this section, are specified in the media type description (see Section E.1 application/did ). For information about how to dereference a DID fragment , see the Decentralized Identifier Resolution (DID Resolution) v0.3 specification.
A
relative
DID
URL
is
any
URL
value
in
a
DID
document
that
does
not
start
with
did:<method-name>:<method-specific-id>
.
More
specifically,
it
is
any
URL
value
that
does
not
start
with
the
ABNF
defined
in
3.1
DID
Syntax
.
The
URL
is
expected
to
reference
a
resource
in
the
same
DID
document
.
Relative
DID
URLs
MAY
contain
relative
path
components,
query
parameters,
and
fragment
identifiers.
When
resolving
a
relative
DID
URL
reference,
the
algorithm
specified
in
RFC3986
Section
5:
Reference
Resolution
MUST
be
used.
The
base
URI
value
is
the
DID
that
is
associated
with
the
DID
subject
,
see
5.1.1
DID
Subject
.
The
scheme
is
did
.
The
authority
is
a
combination
of
<method-name>:<method-specific-id>
,
and
the
path
,
query
,
and
fragment
values
are
those
defined
in
Path
,
Query
,
and
Fragment
,
respectively.
Relative DID URLs are often used to reference verification methods and services in a DID Document without having to use absolute URLs. DID methods where storage size is a consideration might use relative URLs to reduce the storage size of DID documents .
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123456789abcdefghi",
"verificationMethod": [{
"id": "did:example:123456789abcdefghi#key-1",
"type": "Multikey", // external (property value)
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}, ...],
"authentication": [
// a relative DID URL used to reference a verification method above
"#key-1"
]
}
In
the
example
above,
the
relative
DID
URL
value
will
be
transformed
to
an
absolute
DID
URL
value
of
did:example:123456789abcdefghi#key-1
.
This specification defines a data model that can be used to express DID documents and their internal data structures, which can then be serialized into a concrete expression. This section provides a high-level description of the data model, descriptions of the ways different types of properties are expressed in the data model, and instructions for extending the data model.
A DID document consists of a map of entries , where each entry consists of a key/value pair. The DID document data model contains properties that are specified in section 5. Core Properties .
All entry keys in the DID document data model are strings . All entry values are expressed using one of the data types in the table below, and each representation specifies the concrete serialization format of each data type.
| Data Type | Considerations |
|---|---|
| map | A finite ordered sequence of key/value pairs, with no key appearing twice as specified in the Infra Standard . A map is sometimes referred to as an ordered map in the Infra Standard . |
| list | A finite ordered sequence of items as specified in the Infra Standard . |
| set | A finite ordered sequence of items that does not contain the same item twice as specified in the Infra Standard . A set is sometimes referred to as an ordered set in the Infra Standard . |
| datetime | A date and time value that is capable of losslessly expressing all values expressible by a dateTime as specified in [ XMLSCHEMA11-2 ]. |
| string | A sequence of code units often used to represent human readable language as specified in the Infra Standard . |
| integer | A real number without a fractional component as specified in [ XMLSCHEMA11-2 ]. To maximize interoperability, implementers are urged to heed the advice regarding integers in RFC8259, Section 6: Numbers . |
| double | A real number with a fractional component that is often used to approximate arbitrary real numbers as specified in [ XMLSCHEMA11-2 ]. To maximize interoperability, implementers are urged to heed the advice regarding doubles in RFC8259, Section 6: Numbers . |
| boolean | A value that is either true or false as defined in the Infra Standard . |
| null | A value that is used to indicate the lack of a value as defined in the Infra Standard . |
As a result of the data model being defined using terminology from the Infra Standard , property values which can contain more than one item, such as lists , maps , and sets , are explicitly ordered. All list-like value structures in the Infra Standard are ordered, whether or not that order is significant. For the purposes of this specification, unless otherwise stated, ordering of a map or set is not important and implementations are not expected to produce or consume deterministically ordered values.
The data model supports two types of extensibility.
It is always possible for two specific implementations to agree out-of-band to use a mutually understood extension or representation that is not recorded in the repository of Decentralized Identifier Extensions ; interoperability between such implementations and the larger ecosystem will be less reliable.
A DID is associated with a DID document , which is an extension of a controlled identifier document as defined in Controlled Identifiers v1.0 . DID documents are expressed using the data model and can be serialized into a representation . The following sections define the properties in a DID document , including whether these properties are required or optional. These properties describe relationships between the DID subject and the value of the property.
The following tables contain informative references for the core properties defined by this specification, with expected values, and whether or not they are required. The property names in the tables are linked to the normative definitions and more detailed descriptions of each property.
The
property
names
id
,
type
,
and
controller
can
be
present
in
maps
of
different
types
with
possible
differences
in
constraints.
For
example,
an
id
at
the
top-level
of
a
DID
document
is
required
to
be
a
DID,
while
an
id
in
a
service
map
can
be
a
URL.
| Property | Required? | Value constraints | Definition |
|---|---|---|---|
id
|
yes | A string that conforms to rules defined in Section 3.1 DID Syntax . | Section 5.1.1 DID Subject . |
controller
|
no | A string or a set of strings , each of which conforms to rules defined in Section 3.1 DID Syntax . | Section 5.1.2 DID Controller . |
alsoKnownAs
|
no | A set of strings , each of which conforms to the URL syntax or Section 3.1 DID Syntax . | Section 2.1.3: Also Known As of the Controlled Identifiers v1.0 specification. |
service
|
no | A set of service maps . | Section 2.1.4: Services of the Controlled Identifiers v1.0 specification. |
verificationMethod
|
no | A set of verification method maps . | Section 5.2 Verification Methods . |
authentication
|
no | A set of data where each element is either a string which conforms to rules defined in Section 3.1 DID Syntax , or a map that conforms to the rules for verification methods defined in Section 5.2 Verification Methods . | Section 2.3.1: Authentication of the Controlled Identifiers v1.0 specification and Section 5.2 Verification Methods . |
assertionMethod
|
no | A set of data where each element is either a string which conforms to rules defined in Section 3.1 DID Syntax , or a map that conforms to the rules for verification methods defined in Section 5.2 Verification Methods . | Section 2.3.2: Assertion of the Controlled Identifiers v1.0 specification and Section 5.2 Verification Methods . |
keyAgreement
|
no | A set of data where each element is either a string which conforms to rules defined in Section 3.1 DID Syntax , or a map that conforms to the rules for verification methods defined in Section 5.2 Verification Methods . | Section 2.3.3: Key Agreement of the Controlled Identifiers v1.0 specification and Section 5.2 Verification Methods . |
capabilityInvocation
|
no | A set of data where each element is either a string which conforms to rules defined in Section 3.1 DID Syntax , or a map that conforms to the rules for verification methods defined in Section 5.2 Verification Methods . | Section 2.3.4: Capability Invocation of the Controlled Identifiers v1.0 specification and Section 5.2 Verification Methods . |
capabilityDelegation
|
no | A set of data where each element is either a string which conforms to rules defined in Section 3.1 DID Syntax , or a map that conforms to the rules for verification methods defined in Section 5.2 Verification Methods . | Section 2.3.5: Capability Delegation of the Controlled Identifiers v1.0 specification and Section 5.2 Verification Methods . |
| Property | Required? | Value constraints | Definition |
|---|---|---|---|
id
|
yes | A string that conforms to the rules in 3.2 DID URL Syntax . | Section 2.1.1: Subjects of the Controlled Identifiers v1.0 specification and Section 5.1 Identifiers . |
type
|
yes | A string . | Section 2.2: Verification Methods of the Controlled Identifiers v1.0 specification. |
controller
|
yes | A string that conforms to the rules in 3.1 DID Syntax . | Section 2.2: Verification Methods of the Controlled Identifiers v1.0 specification. |
publicKeyMultibase
|
no | A string that conforms to a Multibase-encoded public key. | Section 2.2.2: Multikey of the Controlled Identifiers v1.0 specification. |
publicKeyJwk
|
no | A map representing a JSON Web Key. | Section 2.2.3: JsonWebKey of the Controlled Identifiers v1.0 specification. |
| Property | Required? | Value constraints | Definition |
|---|---|---|---|
id
|
yes | A string that conforms to the rules of either the URL Standard standard, or Section 3.1 DID Syntax . | Section 2.1.1: Subjects of the Controlled Identifiers v1.0 specification. |
type
|
yes | A string or a set of strings . | Section 2.1.4: Services of the Controlled Identifiers v1.0 specification. |
serviceEndpoint
|
yes | A single string , a single map , or a set composed of one or more strings and/or maps . Each string value MUST be a valid URL conforming to URL Standard . | Section 2.1.4: Services of the Controlled Identifiers v1.0 specification. |
This section describes the mechanisms by which DID documents include identifiers for DID subjects and DID controllers .
The
DID
for
a
particular
DID
subject
is
expressed
using
the
id
property
in
the
DID
document
.
This
property
is
defined
in
Section
2.1.1:
Subjects
of
the
Controlled
Identifiers
v1.0
specification
and
extended
by
this
specification
to
include
decentralized
identifiers
as
defined
in
Section
3.1
DID
Syntax
.
{
"id": "did:example:123456789abcdefghijk"
}
DID
method
specifications
can
create
intermediate
representations
of
a
DID
document
,
such
as
when
a
decentralized
identifier
is
being
registered
in
a
verifiable
data
registry
or
when
a
DID
resolver
is
performing
DID
resolution
.
These
intermediate
representations
might
not
contain
id
values,
or
might
contain
interim
values
for
certain
id
properties.
Once
the
DID
document
is
fully
resolved,
the
final
id
value
will
be
determined
and
put
in
place
of
the
interim
values
throughout
the
DID
document
.
A DID controller is an entity that is authorized to make changes to a DID document . This property is defined in Section 2.1.2: Controllers of the Controlled Identifiers v1.0 specification and extended by this specification to include DIDs as defined in Section 3.1 DID Syntax . The process of authorizing a DID controller is defined by the DID method .
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123456789abcdefghi",
"controller": "did:example:bcehfew7h32f32h7af3"
}
Identifiers
used
in
a
DID
document
to
identify
a
DID
subject
or
a
DID
Controller
cannot
use
query
parameters
or
fragment
identifiers.
Implementers
are
urged
to
pay
particular
attention
to
the
list
of
allowable
characters
in
Section
3.1
DID
Syntax
which
makes
this
requirement
clear;
the
syntax
does
not
include
the
?
character
nor
the
#
character.
This
is
in
contrast
to
identifiers
used
in
a
DID
document
to
identify
a
verification
method
or
a
service
,
which
follow
the
syntax
rules
in
Section
3.2
DID
URL
Syntax
,
which
do
allow
the
use
of
query
parameters
and
fragment
identifiers.
Even
so,
the
use
of
query
parameters
in
long-lived
canonical
identifiers
made
for
DID
ecosystems
is
discouraged
as
it
can
increase
the
complexity
of
DID
resolution
software
and
potentially
lead
to
a
larger
security
attack
surface.
Fragment
identifiers
are
also
expected
to
be
unique
within
a
particular
DID
document
and
implementers
are
discouraged
from
reusing
them
to
refer
to
different
resources
over
time,
such
as
two
different
verification
methods
within
the
same
DID
document
.
A
DID
document
can
express
verification
methods
,
as
defined
in
Section
2.2:
Verification
Methods
of
Controlled
Identifiers
v1.0
with
the
added
restrictions
that
(a)
the
id
value
MUST
conform
to
Section
3.2
DID
URL
Syntax
or
Section
3.2.1
Relative
DID
URLs
and
(b)
the
controller
value
MUST
conform
to
Section
3.1
DID
Syntax
.
See
Section
2.2:
Verification
Methods
of
the
Controlled
Identifiers
v1.0
specification
for
a
description
of
verification
methods
.
A DID document can express verification relationships , as defined in Section 2.3: Verification Relationships of the Controlled Identifiers v1.0 specification. See Section 2.3: Verification Relationships of the Controlled Identifiers v1.0 specification for a description of verification methods .
A DID document can express services , as defined in Section 2.1.4: Services of the Controlled Identifiers v1.0 specification. Identifiers used in services can be expressed according to Section 3.1 DID Syntax or Section 3.2 DID URL Syntax . See Section 2.1.4: Services of the Controlled Identifiers v1.0 specification for a description of services .
A concrete serialization of a DID document in this specification is called a representation . A representation is created by serializing the data model through a process called production . A representation is transformed into the data model through a process called consumption . The production and consumption processes enable the conversion of information from one representation to another. This specification defines a single representation for JSON, which is also compatible with processors that perform JSON-LD processing. The following sections define the general rules for production and consumption , as well as the JSON representation .
In addition to the representations defined in this specification, implementers can use other representations , providing each such representation is properly specified (including rules for interoperable handling of properties not listed in the repository of DID Extensions [ DID-EXTENSIONS ]). See 4.1 Extensibility for more information.
The requirements for all representations are as follows:
dateTime
lexical
serialization
to
represent
datetimes
.
A
representation
MAY
choose
to
serialize
the
data
model
data
types
using
a
different
lexical
serializations
as
long
as
the
consumption
process
back
into
the
data
model
is
lossless.
For
example,
some
CBOR-based
representations
express
datetime
values
using
integers
to
represent
the
number
of
seconds
since
the
Unix
epoch.
The requirements for all conforming producers are as follows:
The requirements for all conforming consumers are as follows:
The upper left quadrant of the diagram contains a rectangle with dashed grey outline, containing two blue-outlined rectangles, one above the other. The upper, larger rectangle is labeled, in blue, "Core Properties", and contains the following INFRA notation:
«[
"id" → "example:123",
"verificationMethod" → « «[
"id": "did:example:123#keys-1",
"controller": "did:example:123",
"type": "Multikey",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
]» »,
"authentication" → «
"did:example:123#keys-1"
»
]»
The
lower,
smaller
rectangle
is
labeled,
in
blue,
"Core
Representation-specific
Entries
(JSON-LD)",
and
contains
the
following
monospaced
INFRA
notation:
«
[
"@context"
→
"https://www.w3.org/ns/did/v1.1"
]
»
From the grey-outlined rectangle, three pairs of arrows extend to three different black-outlined rectangles, one on the upper right of the diagram, one in the lower right, and one in the lower left. Each pair of arrows consists of one blue arrow pointing from the grey-outlined rectangle to the respective black-outlined rectangle, labeled "produce", and one red arrow pointing in the reverse direction, labeled "consume". The black-outlined rectangle in the upper right is labeled "application/did+cbor", and contains hexadecimal data. The rectangle in the lower right is labeled "application/did", and contains the following JSON data:
{
"id": "did:example:123",
"verificationMethod": [{
"id": "did:example:123#keys-1",
"controller": "did:example:123",
"type": "Multikey",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}],
"authentication": [
"did:example:123#keys-1"
]
}
The rectangle in the lower left is labeled "application/did", and contains the following JSON-LD data:
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123",
"verificationMethod": [{
"id": "did:example:123#keys-1",
"controller": "did:example:123",
"type": "Multikey",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}],
"authentication": [
"did:example:123#keys-1"
]
}
An implementation is expected to convert between representations by using the consumption rules on the source representation resulting in the data model and then using the production rules to serialize data model to the target representation, or any other mechanism that results in the same target representation.
This section defines the production and consumption rules for the JSON representation .
The DID document , DID document data structures, and representation-specific entries map MUST be serialized to the JSON representation according to the following production rules:
| Data Type | JSON Representation Type |
|---|---|
| map | A JSON Object , where each entry is serialized as a member of the JSON Object with the entry key as a JSON String member name and the entry value according to its type, as defined in this table. |
| list | A JSON Array , where each element of the list is serialized, in order, as a value of the array according to its type, as defined in this table. |
| set | A JSON Array , where each element of the set is added, in order, as a value of the array according to its type, as defined in this table. |
| datetime |
A
JSON
String
serialized
as
an
XML
Datetime
normalized
to
UTC
00:00:00
and
without
sub-second
decimal
precision.
For
example:
2020-12-20T19:17:47Z
.
|
| string | A JSON String . |
| integer | A JSON Number without a decimal or fractional component. |
| double | A JSON Number with a decimal and fractional component. |
| boolean | A JSON Boolean . |
| null | A JSON null literal . |
All implementers creating conforming producers that produce JSON representations are advised to ensure that their algorithms are aligned with the JSON serialization rules in the [ INFRA ] specification and the precision advisements regarding Numbers in the JSON [ RFC8259 ] specification.
All
entries
of
a
DID
document
MUST
be
included
in
the
root
JSON
Object
.
Entries
MAY
contain
additional
data
substructures
subject
to
the
value
representation
rules
in
the
list
above.
When
serializing
a
DID
document
,
a
conforming
producer
MUST
specify
a
media
type
of
application/did
to
downstream
applications.
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123456789abcdefghi",
"authentication": [{
"id": "did:example:123456789abcdefghi#keys-1",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}]
}
The DID document and DID document data structures JSON representation MUST be deserialized into the data model according to the following consumption rules:
| JSON Representation Type | Data Type |
|---|---|
| JSON Object | A map , where each member of the JSON Object is added as an entry to the map. Each entry key is set as the JSON Object member name. Each entry value is set by converting the JSON Object member value according to the JSON representation type as defined in this table. Since order is not specified by JSON Objects, no insertion order is guaranteed. |
| JSON Array where the data model entry value is a list or unknown | A list , where each value of the JSON Array is added to the list in order, converted based on the JSON representation type of the array value, as defined in this table. |
| JSON Array where the data model entry value is a set | A set , where each value of the JSON Array is added to the set in order, converted based on the JSON representation type of the array value, as defined in this table. |
| JSON String where data model entry value is a datetime | A datetime . |
| JSON String , where the data model entry value type is string or unknown | A string . |
| JSON Number without a decimal or fractional component | An integer . |
| JSON Number with a decimal and fractional component, or when entry value is a double regardless of inclusion of fractional component | A double . |
| JSON Boolean | A boolean . |
| JSON null literal | A null value. |
All implementers creating conforming producers or conforming consumers are advised to ensure that their algorithms are aligned with the JSON conversion rules in the [ INFRA ] specification and the precision advisements regarding Numbers in the JSON [ RFC8259 ] specification.
If
media
type
information
is
available
to
a
conforming
consumer
and
the
media
type
value
is
application/did
,
then
the
data
structure
being
consumed
is
a
DID
document
,
and
the
root
element
MUST
be
a
JSON
Object
where
all
members
of
the
object
are
entries
of
the
DID
document
.
A
conforming
consumer
for
a
JSON
representation
that
is
consuming
a
DID
document
with
a
root
element
that
is
not
a
JSON
Object
MUST
report
an
error.
JSON-LD is a JSON-based format used to serialize Linked Data . Some implementations are expected to process DID documents using the standard JSON-LD Processing algorithms. To maximize interoperability, implementers are strongly advised to ensure that JSON-LD Processing using standards-compliant libraries is not prevented. The semantics of a DID document are the same whether JSON-LD Processing using standards-compliant libraries is performed or not. Any difference in semantics is an error in either implementation or DID Method specification.
For
JSON-LD
processing
to
occur,
a
@context
property
MUST
be
specified
according
to
the
rules
specified
in
the
JSON-LD
1.1
specification.
The DID document , DID document data structures, and representation-specific entries map MUST be serialized to the JSON representation according to the JSON representation production rules as defined in 6.2 JSON .
In
addition
to
using
the
JSON
representation
production
rules,
production
MUST
include
the
@context
entry.
The
serialized
value
of
@context
MUST
be
the
JSON
String
https://www.w3.org/ns/did/v1.1
,
or
a
JSON
Array
where
the
first
item
is
the
JSON
String
https://www.w3.org/ns/did/v1.1
and
the
subsequent
items
are
serialized
according
to
the
JSON
production
rules.
{
"@context": "https://www.w3.org/ns/did/v1.1",
...
}
{
"@context": [
"https://www.w3.org/ns/did/v1.1",
"https://did-method-extension.example/v1"
],
...
}
All implementers creating conforming consumers that produce or consume representations meant to be processed as JSON-LD are advised to ensure that their algorithms produce valid JSON-LD documents. Invalid JSON-LD documents will cause JSON-LD processors to halt and report errors.
To achieve interoperability across different representations , all JSON-LD Contexts and their terms SHOULD be registered in the repository of Decentralized Identifier Extensions .
A
conforming
producer
that
generates
a
JSON-LD
representation
SHOULD
NOT
produce
a
DID
document
that
contains
terms
not
defined
via
the
@context
as
conforming
consumers
are
expected
to
remove
unknown
terms.
When
serializing
a
JSON-LD
representation
of
a
DID
document
,
a
conforming
producer
MUST
specify
a
media
type
of
application/did
to
downstream
applications.
Conforming
consumers
that
process
a
JSON-LD
representation
SHOULD
drop
all
terms
from
a
DID
document
that
are
not
defined
via
the
@context
.
Media types, as defined in [ RFC6838 ], identify the syntax used to express a DID document as well as other useful processing guidelines.
Syntaxes used to express the data model in this specification SHOULD be identified by a media type, and conventions outlined in this section SHOULD be followed when defining or using media types with DID documents .
There
is
one
media
type
associated
with
the
core
data
model,
which
is
listed
in
Section
E.
IANA
Considerations
:
application/did
.
This section is non-normative.
At times, developers or systems might use lower-precision media types to convey DID documents . Some of the reasons for use of lower-precision media types include:
text/plain
or
application/octet-stream
when
a
file
extension
is
not
available
and
it
cannot
determine
the
media
type.
.json
could
result
in
a
media
type
of
application/json
and
.jsonld
might
result
in
a
media
type
of
application/ld+json
.
application/json
instead
of
application/did
,
Implementers
are
discouraged
from
raising
errors
when
it
is
possible
to
determine
the
intended
media
type
from
the
payload,
provided
that
the
media
type
used
is
acceptable
in
the
given
protocol.
For
example,
if
an
application
only
accepts
payloads
that
conform
to
the
rules
associated
with
the
application/did
media
type,
but
the
payload
is
tagged
with
the
lower-precision
application/json
or
application/ld+json
,
the
application
might
perform
the
following
steps
to
determine
whether
the
payload
also
conforms
to
the
higher-precision
media
type:
@context
property
matches
https://www.w3.org/ns/did/v1.1
.
application/did
media
type
if
the
JSON
document
contains
a
top-level
id
property
containing
an
identifier
that
conforms
to
the
rules
in
Section
3.1
DID
Syntax
.
Whenever possible, implementers are advised to use the most precise (the highest- precision) media type for all payloads defined by this specification. Implementers are also advised to recognize that a payload tagged with a lower- precision media type does not mean that the payload does not meet the rules necessary to tag it with a higher-precision type. Similarly, a payload tagged with a higher-precision media type does not mean that the payload will meet the requirements associated with the media type. Receivers of payloads, regardless of their associated media type, are expected to perform appropriate checks to ensure that payloads conform with the requirements for their use in a given system.
HTTP
clients
and
servers
use
media
types
associated
with
DID
documents
in
Accept:
headers
and
when
indicating
content
types.
Implementers
are
warned
that
HTTP
servers
might
ignore
the
Accept:
header
and
return
another
content
type,
or
return
an
error
code
such
as
415
Unsupported
Media
Type
.
A conforming DID method defines how implementers can realize the features described by this specification. DID methods are often associated with a particular verifiable data registry . New DID methods are defined in their own specifications to enable interoperability between different implementations of the same DID method .
Conceptually,
the
relationship
between
this
specification
and
a
DID
method
specification
is
similar
to
the
relationship
between
the
IETF
generic
URI
specification
[
RFC3986
]
and
a
specific
URI
scheme
[
IANA-URI-SCHEMES
],
such
as
the
http
scheme
[
RFC9110
].
In
addition
to
defining
a
specific
DID
scheme
,
a
DID
method
specification
also
defines
the
mechanisms
for
creating,
resolving,
updating,
and
deactivating
DIDs
and
DID
documents
using
a
specific
type
of
verifiable
data
registry
.
It
also
documents
all
implementation
considerations
related
to
DIDs
as
well
as
Security
and
Privacy
Considerations.
This section specifies the requirements for authoring DID method specifications.
The requirements for all DID method specifications when defining the method-specific DID Syntax are as follows:
method-name
rule
in
3.1
DID
Syntax
.
method-specific-id
component
of
a
DID
.
method-specific-id
.
method-specific-id
value
MUST
be
unique
within
a
DID
method
.
The
method-specific-id
value
itself
might
be
globally
unique.
method-name
conflicts,
a
DID
method
specification
SHOULD
be
registered
in
the
repository
of
DID
Extensions
[
DID-EXTENSIONS
].
method-specific-id
formats.
method-specific-id
format
MAY
include
colons.
The
use
of
colons
MUST
comply
syntactically
with
the
method-specific-id
ABNF
rule.
The
meaning
of
colons
in
the
method-specific-id
is
entirely
method-specific.
Colons
might
be
used
by
DID
methods
for
establishing
hierarchically
partitioned
namespaces,
for
identifying
specific
instances
or
parts
of
the
verifiable
data
registry
,
or
for
other
purposes.
Implementers
are
advised
to
avoid
assuming
any
meanings
or
behaviors
associated
with
a
colon
that
are
generically
applicable
to
all
DID
methods
.
The requirements for all DID method specifications when defining the method operations are as follows:
The authority of a party that is performing authorization to carry out the operations is specific to a DID method . For example, a DID method might —
controller
property.
authentication
.
capabilityInvocation
verification
relationship
.
When executing method operations, a DID method can use any data structures it requires, including intermediate, partial, or temporary DID documents , as long as they are kept internal to the DID method, and the DID documents returned by the method operations are fully conformant, as defined in 1.4 Conformance .
The requirements for all DID method specifications when authoring the Security Considerations section are as follows:
The requirements for all DID method specifications when authoring the Privacy Considerations section are:
This section is non-normative.
This section contains a variety of security considerations that people using Decentralized Identifiers are advised to consider before deploying this technology in a production setting. Readers are urged to read the Security Considerations section of the Controlled Identifiers v1.0 specification before reading this section. DIDs are designed to operate under the threat model used by many IETF standards and documented in [ RFC3552 ]. This section elaborates upon a number of the considerations in [ RFC3552 ], as well as other considerations that are unique to DID architecture.
The repository of DID Extensions [ DID-EXTENSIONS ] contains an informative list of DID method names and their corresponding DID method specifications. Implementers need to bear in mind that there is no central authority to mandate which DID method specification is to be used with any specific DID method name. If there is doubt on whether or not a specific DID resolver implements a DID method correctly, the DID Specification Registries can be used to look up the registered specification and make an informed decision regarding which DID resolver implementation to use.
Non-repudiation of DIDs and DID document updates is supported if:
One mitigation against unauthorized changes to a DID document is monitoring and actively notifying the DID subject when there are changes. This is analogous to helping prevent account takeover on conventional username/password accounts by sending password reset notifications to the email addresses on file.
In the case of a DID , there is no intermediary registrar or account provider to generate such notifications. However, if the verifiable data registry on which the DID is registered directly supports change notifications, a subscription service can be offered to DID controllers . Notifications could be sent directly to the relevant service endpoints listed in an existing DID .
If a DID controller chooses to rely on a third-party monitoring service (other than the verifiable data registry itself), this introduces another vector of attack.
Trustless
systems
are
those
where
all
trust
is
derived
from
cryptographically
provable
assertions,
and
more
specifically,
where
no
metadata
outside
of
the
cryptographic
system
is
factored
into
the
determination
of
trust
in
the
system.
To
verify
a
signature
of
proof
for
a
verification
method
which
has
been
revoked
in
a
trustless
system,
a
DID
method
needs
to
support
either
or
both
of
the
versionId
or
versionTime
,
as
well
as
both
the
updated
and
nextUpdate
,
DID
document
metadata
properties.
A
verifier
can
validate
a
signature
or
proof
of
a
revoked
key
if
and
only
if
all
of
the
following
are
true:
versionId
or
versionTime
of
the
DID
document
that
was
used
at
the
point
in
time
at
which
the
signature
or
proof
was
made.
updated
timestamp
is
before,
and
the
nextUpdate
timestamp
is
after,
the
point
in
time
at
which
the
signature
or
proof
was
made.
Similar trust may be achieved in systems that are willing to accept metadata beyond that which constitutes cryptographic input -- but this always requires a careful judgment about whether a DID document 's content included the expected content at the moment of a signing event.
Recovery is a reactive security measure whereby a controller that has lost the ability to perform DID operations, such as through the loss of a device, is able to regain the ability to perform DID operations.
The following considerations might be of use when contemplating the use of DID recovery:
DIDs achieve global uniqueness without the need for a central registration authority. This comes at the cost of human memorability. Algorithms capable of generating globally unambiguous identifiers produce random strings of characters that have no human meaning. This trade-off is often referred to as Zooko's Triangle .
There are use cases where it is desirable to discover a DID when starting from a human-friendly identifier. For example, a natural language name, a domain name, or a conventional address for a DID controller , such as a mobile telephone number, email address, social media username, or blog URL. However, the problem of mapping human-friendly identifiers to DIDs , and doing so in a way that can be verified and trusted, is outside the scope of this specification.
Solutions to this problem are defined in separate specifications, such as [ DNS-DID ], that reference this specification. It is strongly recommended that such specifications carefully consider the:
If desired by a DID controller , a DID or a DID URL is capable of acting as persistent, location-independent resource identifier. These sorts of identifiers are classified as Uniform Resource Names (URNs) and are defined in [ RFC8141 ]. DIDs are an enhanced form of URN that provide a cryptographically secure, location-independent identifier for a digital resource, while also providing metadata that enables retrieval. Due to the indirection between the DID document and the DID itself, the DID controller can adjust the actual location of the resource — or even provide the resource directly — without adjusting the DID . DIDs of this type can definitively verify that the resource retrieved is, in fact, the resource identified.
A DID controller who intends to use a DID for this purpose is advised to follow the security considerations in [ RFC8141 ]. In particular:
Many cybersecurity abuses hinge on exploiting gaps between reality and the assumptions of rational, good-faith actors. Immutability of DID documents can provide some security benefits. Individual DID methods ought to consider constraints that would eliminate behaviors or semantics they do not need. The more locked down a DID method is, while providing the same set of features, the less it can be manipulated by malicious actors.
As
an
example,
consider
that
a
single
edit
to
a
DID
document
can
change
anything
except
the
root
id
property
of
the
document.
But
is
it
actually
desirable
for
a
service
to
change
its
type
after
it
is
defined?
Or
for
a
key
to
change
its
value?
Or
would
it
be
better
to
require
a
new
id
when
certain
fundamental
properties
of
an
object
change?
Malicious
takeovers
of
a
website
often
aim
for
an
outcome
where
the
site
keeps
its
host
name
identifier,
but
is
subtly
changed
underneath.
If
certain
properties
of
the
site,
such
as
the
ASN
associated
with
its
IP
address,
were
required
by
the
specification
to
be
immutable,
anomaly
detection
would
be
easier,
and
attacks
would
be
much
harder
and
more
expensive
to
carry
out.
For DID methods tied to a global source of truth, a direct, just-in-time lookup of the latest version of a DID document is always possible. However, it seems likely that layers of cache might eventually sit between a DID resolver and that source of truth. If they do, believing the attributes of an object in the DID document to have a given state when they are actually subtly different might invite exploits. This is particularly true if some lookups are of a full DID document , and others are of partial data where the larger context is assumed.
Encryption algorithms have been known to fail due to advances in cryptography and computing power. Implementers are advised to assume that any encrypted data placed in a DID document might eventually be made available in clear text to the same audience to which the encrypted data is available. This is particularly pertinent if the DID document is public.
Encrypting all or parts of a DID document is not an appropriate means to protect data in the long term. Similarly, placing encrypted data in a DID document is not an appropriate means to protect personal data.
Given the caveats above, if encrypted data is included in a DID document , implementers are advised to not associate any correlatable information that could be used to infer a relationship between the encrypted data and an associated party. Examples of correlatable information include public keys of a receiving party, identifiers to digital assets known to be under the control of a receiving party, or human readable descriptions of a receiving party.
Given
the
equivalentId
and
canonicalId
properties
are
generated
by
DID
methods
themselves,
the
same
security
and
accuracy
guarantees
that
apply
to
the
resolved
DID
present
in
the
id
field
of
a
DID
document
also
apply
to
these
properties.
The
alsoKnownAs
property
is
not
guaranteed
to
be
an
accurate
statement
of
equivalence,
and
should
not
be
relied
upon
without
performing
validation
steps
beyond
the
resolution
of
the
DID
document
.
The
equivalentId
and
canonicalId
properties
express
equivalence
assertions
to
variants
of
a
single
DID
produced
by
the
same
DID
method
and
can
be
trusted
to
the
extent
the
requesting
party
trusts
the
DID
method
and
a
conforming
producer
and
resolver.
The
alsoKnownAs
property
permits
an
equivalence
assertion
to
URIs
that
are
not
governed
by
the
same
DID
method
and
cannot
be
trusted
without
performing
verification
steps
outside
of
the
governing
DID
method
.
See
additional
guidance
in
Section
2.1.3:
Also
Known
As
of
the
Controlled
Identifiers
v1.0
specification.
As with any other security-related properties in the DID document , parties relying on any equivalence statement in a DID document should guard against the values of these properties being substituted by an attacker after the proper verification has been performed. Any write access to a DID document stored in memory or disk after verification has been performed is an attack vector that might circumvent verification unless the DID document is re-verified.
DIDs are designed to be persistent such that a controller need not rely upon a single trusted third party or administrator to maintain their identifiers. In an ideal case, no administrator can take control away from the controller , nor can an administrator prevent their identifiers' use for any particular purpose such as authentication, authorization, and attestation. No third party can act on behalf of a controller to remove or render inoperable an entity's identifier without the controller 's consent.
However, it is important to note that in all DID methods that enable cryptographic proof-of-control, the means of proving control can always be transferred to another party by transferring the secret cryptographic material. Therefore, it is vital that systems relying on the persistence of an identifier over time regularly check to ensure that the identifier is, in fact, still under the control of the intended party.
Unfortunately, it is impossible to determine from the cryptography alone whether or not the secret cryptographic material associated with a given verification method has been compromised. It might well be that the expected controller still has access to the secret cryptographic material — and as such can execute a proof-of-control as part of a verification process — while at the same time, a bad actor also has access to those same keys, or to a copy thereof.
As such, cryptographic proof-of-control is expected to only be used as one factor in evaluating the level of identity assurance required for high-stakes scenarios. DID -based authentication provides much greater assurance than a username and password, thanks to the ability to determine control over a cryptographic secret without transmitting that secret between systems. However, it is not infallible. Scenarios that involve sensitive, high value, or life-critical operations are expected to use additional factors as appropriate.
In addition to potential ambiguity from use by different controllers , it is impossible to guarantee, in general, that a given DID is being used in reference to the same subject at any given point in time. It is technically possible for the controller to reuse a DID for different subjects and, more subtly, for the precise definition of the subject to either change over time or be misunderstood.
For example, consider a DID used for a sole proprietorship, receiving various credentials used for financial transactions. To the controller , that identifier referred to the business. As the business grows, it eventually gets incorporated as a Limited Liability Company. The controller continues using that same DID , because to them the DID refers to the business. However, to the state, the tax authority, and the local municipality, the DID no longer refers to the same entity. Whether or not the subtle shift in meaning matters to a credit provider or supplier is necessarily up to them to decide. In many cases, as long as the bills get paid and collections can be enforced, the shift is immaterial.
Due to these potential ambiguities, DIDs are to be considered valid contextually rather than absolutely. Their persistence does not imply that they refer to the exact same subject, nor that they are under the control of the same controller . Instead, one needs to understand the context in which the DID was created, how it is used, and consider the likely shifts in their meaning, and adopt procedures and policies to address both potential and inevitable semantic drift.
This section is non-normative.
This specification does not require or suggest the use of any specific type of verifiable data registry . Different use cases might result in different requirements. Different requirements might suggest different considerations with different trade-offs. For example, trade-offs between computation (energy usage), trust (deference to authority), coordination (network bandwidth), or memory (physical storage) might or might not be appropriate for any given use case. Other use cases might not make the same trade-offs. Those that need to consider different criteria for their use case are directed to the DID Method Rubric , which provides evaluation criteria to help decision makers determine whether or not a particular DID Method is appropriate for their use cases.
This section is non-normative.
Since DIDs and DID documents are designed to be administered directly by the DID controller(s) , it is critically important to apply the principles of Privacy by Design [ PRIVACY-BY-DESIGN ] to all aspects of the decentralized identifier architecture. All seven of these principles have been applied throughout the development of this specification. The design used in this specification does not assume that there is a registrar, hosting company, nor other intermediate service provider to recommend or apply additional privacy safeguards. Privacy in this specification is preventive, not remedial, and is an embedded default. Before reading this section, readers are urged to read the Privacy Considerations section of the Controlled Identifiers v1.0 specification, as it contains more general privacy considerations that also apply to DIDs . The rest of this section covers privacy considerations that are specific to decentralized identifiers and are in addition to the guidance provided in the Controlled Identifiers v1.0 specification.
When a DID subject is indistinguishable from others in the group, privacy is available. When the act of engaging privately with another party is by itself a recognizable flag, privacy is greatly diminished.
DIDs and DID methods need to work to improve group privacy, particularly for those who legitimately need it most. Choose technologies and human interfaces that default to preserving anonymity and pseudonymity. To reduce digital fingerprints , share common settings across requesting party implementations, keep negotiated options to a minimum on wire protocols, use encrypted transport layers, and pad messages to standard lengths.
This section is non-normative.
This section is non-normative.
See Verification Method Types [ DID-EXTENSIONS ] for optional extensions and other verification method types.
These examples are for information purposes only, it is considered a best practice to avoid using the same verification method for multiple purposes.
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123",
"authentication": [
{
"id": "did:example:123#z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu",
"type": "Multikey", // external (property value)
"controller": "did:example:123",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
"capabilityInvocation": [
{
"id": "did:example:123#z6Mkvtac9bidSz9bBttzn7Yg3oCDHvMY2FtkFLs6SXRQGdQR",
"type": "Multikey", // external (property value)
"controller": "did:example:123",
"publicKeyMultibase": "z6Mkvtac9bidSz9bBttzn7Yg3oCDHvMY2FtkFLs6SXRQGdQR"
}
],
"capabilityDelegation": [
{
"id": "did:example:123#z6MknxsdF4CGVxhRNsx6TvXPFczaHEkajKBBwu75uwBmgpom",
"type": "Multikey", // external (property value)
"controller": "did:example:123",
"publicKeyMultibase": "z6MknxsdF4CGVxhRNsx6TvXPFczaHEkajKBBwu75uwBmgpom"
}
],
"assertionMethod": [
{
"id": "did:example:123#z6MkgYhVuWq4hyc7ZKBGhsY7pb5Bc8V6VPXGPG3EPja8JBFR",
"type": "Multikey", // external (property value)
"controller": "did:example:123",
"publicKeyMultibase": "z6MkgYhVuWq4hyc7ZKBGhsY7pb5Bc8V6VPXGPG3EPja8JBFR"
}
]
}
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123",
"verificationMethod": [
{
"id": "did:example:123#key-0",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "OKP", // external (property name)
"crv": "Ed25519", // external (property name)
"x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ" // external (property name)
}
},
{
"id": "did:example:123#key-1",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "OKP", // external (property name)
"crv": "X25519", // external (property name)
"x": "pE_mG098rdQjY3MKK2D5SUQ6ZOEW3a6Z6T7Z4SgnzCE" // external (property name)
}
},
{
"id": "did:example:123#key-2",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "secp256k1", // external (property name)
"x": "Z4Y3NNOxv0J6tCgqOBFnHnaZhJF6LdulT7z8A-2D5_8", // external (property name)
"y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk" // external (property name)
}
},
{
"id": "did:example:123#key-3",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "secp256k1", // external (property name)
"x": "U1V4TVZVMUpUa0ZVU1NBcU9CRm5IbmFaaEpGNkxkdWx", // external (property name)
"y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk" // external (property name)
}
},
{
"id": "did:example:123#key-4",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-256", // external (property name)
"x": "Ums5WVgwRkRTVVFnU3k5c2xvZllMbEcwM3NPRW91ZzN", // external (property name)
"y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4" // external (property name)
}
},
{
"id": "did:example:123#key-5",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-384", // external (property name)
"x": "VUZKSlUwMGdpSXplekRwODhzX2N4U1BYdHVYWUZsaXVDR25kZ1U0UXA4bDkxeHpE", // external (property name)
"y": "jq4QoAHKiIzezDp88s_cxSPXtuXYFliuCGndgU4Qp8l91xzD1spCmFIzQgVjqvcP" // external (property name)
}
},
{
"id": "did:example:123#key-6",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-521", // external (property name)
"x": "VTI5c1lYSmZWMmx1WkhNZ0dQTXhaYkhtSnBEU3UtSXZwdUtpZ0VOMnB6Z1d0U28tLVJ3ZC1uNzhuclduWnplRGMx", // external (property name)
"y": "UW5WNVgwSnBkR052YVc0Z1VqY1B6LVpoZWNaRnliT3FMSUpqVk9sTEVUSDd1UGx5RzBnRW9NV25JWlhoUVZ5cFB5" // external (property name)
}
},
{
"id": "did:example:123#key-7",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "RSA", // external (property name)
"e": "AQAB", // external (property name)
"n": "UkhWaGJGOUZRMTlFVWtKSElBdENGV2hlU1F2djFNRXh1NVJMQ01UNGpWazlraEpLdjhKZU1YV2UzYldIYXRqUHNrZGYyZGxhR2tXNVFqdE9uVUtMNzQybXZyNHRDbGRLUzNVTElhVDFoSkluTUhIeGoyZ2N1Yk82ZUVlZ0FDUTRRU3U5TE8wSC1MTV9MM0RzUkFCQjdRamE4SGVjcHl1c3BXMVR1X0RicXhjU253ZW5kYW13TDUyVjE3ZUtobE80dVh3djJIRmx4dWZGSE0wS21DSnVqSUt5QXhqRF9tM3FfX0lpSFVWSEQxdERJRXZMUGhHOUF6c24zajk1ZC1zYU" // external (property name)
}
}
]
}
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123",
"verificationMethod": [{
"id": "did:example:123#key-0",
"type": "Multikey",
"controller": "did:example:123",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}, {
"id": "did:example:123#key-1",
"type": "Multikey",
"controller": "did:example:123",
"publicKeyMultibase": "z6MtTjFFxQ4sQKS2wmozFAn5cxukmM46WR7e2vxfqZQsv4eh"
}, {
"id": "did:example:123#key-2",
"type": "EcdsaSecp256k1VerificationKey2019",
"controller": "did:example:123",
"publicKeyMultibase": "zns2aFDq25fEV1NUd3wZ65sgtht4j5QjFW8JCAHdUJfLwfodt"
}, {
"id": "did:example:123#key-3",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-256", // external (property name)
"x": "Er6KSSnAjI70ObRWhlaMgqyIOQYrDJTE94ej5hybQ2M",
"y": "pPVzCOTJwgikPjuUE6UebfZySqEJ0ZtsWFpj7YSPGEk"
}
}]
}
{
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123",
"verificationMethod": [
{
// A relative DID URL, that will be transformed to the absolute DID URL value did:example:123#key-1
"id": "#key-1",
"type": "Ed25519VerificationKey2020",
"controller": "did:example:123",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
"authentication": [
"#key-1"
],
"capabilityInvocation": [
"#key-1"
],
"capabilityDelegation": [
"#key-1"
],
"assertionMethod": [
// Using relative DID URL #key-1 is equivalent to using the absolute DID URL value did:example:123#key-1
"did:example:123#key-1"
]
}
This section is non-normative.
These examples are for information purposes only. See Verifiable Credentials Data Model v2.0 for additional examples.
{
// external (all terms in this example)
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v4rc1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCardCredential"
],
"issuer": {
"id": "did:key:zDnaeYGXycLmAn5m9akGtdL6rqBspGQPM7QZXW2CvJ3k9c2Bz",
"image": "data:image/png;base64,iVBORw0KGgo...5CYII="
},
"name": "Permanent Resident Card",
"description": "Government of Utopia Permanent Resident Card.",
"credentialSubject": {
"type": [
"PermanentResident",
"Person"
],
"givenName": "JANE",
"familyName": "SMITH",
"gender": "Female",
"image": "data:image/png;base64,iVBORw0KGgoAA...kJggg==",
"residentSince": "2015-01-01",
"commuterClassification": "C1",
"birthCountry": "Arcadia",
"birthDate": "1978-07-17",
"permanentResidentCard": {
"type": "PermanentResidentCard",
"identifier": "83627465",
"lprCategory": "C09",
"lprNumber": "999-999-999"
}
},
"validFrom": "2025-01-04T00:00:00Z",
"validUntil": "2026-01-04T23:59:59Z",
"proof": {
"type": "DataIntegrityProof",
"created": "2025-01-04T15:02:36Z",
"verificationMethod": "did:key:zDnaeYGXycLmAn5m9akGtdL6rqBspGQPM7QZXW2CvJ3k9c2Bz#zDnaeYGXycLmAn5m9akGtdL6rqBspGQPM7QZXW2CvJ3k9c2Bz",
"cryptosuite": "ecdsa-rdfc-2019",
"proofPurpose": "assertionMethod",
"proofValue": "z5CK4DPN7...Jpqwp"
}
}
{ // external (all terms in this example)
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v4rc1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCardCredential"
],
"issuer": {
"id": "did:example:123#key-1",
"image": "data:image/png;base64,iVBORw0KGgo...5CYII="
},
"name": "Permanent Resident Card",
"description": "Government of Utopia Permanent Resident Card.",
"credentialSubject": {
"type": [
"PermanentResident",
"Person"
],
"givenName": "JANE",
"familyName": "SMITH",
"gender": "Female",
"image": "data:image/png;base64,iVBORw0KGgoAA...kJggg==",
"residentSince": "2015-01-01",
"commuterClassification": "C1",
"birthCountry": "Arcadia",
"birthDate": "1978-07-17",
"permanentResidentCard": {
"type": "PermanentResidentCard",
"identifier": "83627465",
"lprCategory": "C09",
"lprNumber": "999-999-999"
}
},
"validFrom": "2025-01-04T00:00:00Z",
"validUntil": "2026-01-04T23:59:59Z",
"proof": {
"type": "DataIntegrityProof",
"created": "2025-01-04T15:02:36Z",
"verificationMethod": "did:example:123#key-1",
"cryptosuite": "ecdsa-jcs-2019",
"proofPurpose": "assertionMethod",
"proofValue": "z5m9akGtdL...6rqBspGQP"
}
}
{ // external (all terms in this example)
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v4rc1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCardCredential"
],
"issuer": {
"id": "did:key:zUC7DojAAkoD8WpSS87KG6iuMSBd4wH1fZzmcwmakx4JfaXN7RLSES4wNCfWboHvULxGxRwiSsj6UYSgq1dWGusdwrrJsjUQQEb1oid3igF4hbSFzFjf9aWTJSphhu63vHGoAVE",
"image": "data:image/png;base64,iVBORw0KGgoAA...CYII="
},
"name": "Permanent Resident Card",
"description": "Government of Utopia Permanent Resident Card.",
"credentialSubject": {
"type": [
"PermanentResident",
"Person"
],
"givenName": "JANE",
"familyName": "SMITH",
"gender": "Female",
"image": "data:image/png;base64,iVBORw0KGgoAAA...3dgg==",
"residentSince": "2015-01-01",
"commuterClassification": "C1",
"birthCountry": "Arcadia",
"birthDate": "1978-07-17",
"permanentResidentCard": {
"type": "PermanentResidentCard",
"identifier": "83627465",
"lprCategory": "C09",
"lprNumber": "999-999-999"
}
},
"validFrom": "2025-01-04T00:00:00Z",
"validUntil": "2026-01-04T23:59:59Z",
"proof": {
"type": "DataIntegrityProof",
"verificationMethod": "did:key:zUC7DojAAkoD8WpSS87KG6iuMSBd4wH1fZzmcwmakx4JfaXN7RLSES4wNCfWboHvULxGxRwiSsj6UYSgq1dWGusdwrrJsjUQQEb1oid3igF4hbSFzFjf9aWTJSphhu63vHGoAVE#zUC7DojAAkoD8WpSS87KG6iuMSBd4wH1fZzmcwmakx4JfaXN7RLSES4wNCfWboHvULxGxRwiSsj6UYSgq1dWGusdwrrJsjUQQEb1oid3igF4hbSFzFjf9aWTJSphhu63vHGoAVE",
"cryptosuite": "bbs-2023",
"proofPurpose": "assertionMethod",
"proofValue": "u2V0ChVhQik2d4...pc3N1ZXI"
}
}
{
// external (all terms in this example)
"@context": "https://www.w3.org/ns/credentials/v2",
"type": "VerifiablePresentation",
// holder did:key is pairwise to the domain to avoid correlation
"holder": "did:key:z6MkveKdpgkQ1pwNktQ5Lc19epBrzFjMUeNMUZGFvezFF2dX",
"verifiableCredential": {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v4rc1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCardCredential"
],
"issuer": {
"id": "did:web:unlinkable.example",
"image": "data:image/png;base64,iVBORw0KGgoAA...CYII="
},
"credentialSubject": {
"type": ["PermanentResident", "Person"],
// only country is selectively disclosed
"birthCountry": "Arcadia"
},
"proof": {
"type": "DataIntegrityProof",
"verificationMethod": "did:web:vcplayground.org#zUC7EwMqo9vCjFmj7ArU2SivcbeccAY6hd4nw5fVD6xD4W2vm9eVy6VqVnciAZRmPLXnuxuka5JTJVmgz66CxDno6eqZmvUViCckCcKg8A4s1R4i2JjyzrdTQs5zrfY4jJCHFCp",
"cryptosuite": "bbs-2023",
"proofPurpose": "assertionMethod",
"proofValue": "u2V0DhV...3JnIn0"
}
},
"proof": {
"type": "DataIntegrityProof",
"created": "2025-01-04T15:10:39Z",
"verificationMethod": "did:key:z6MkveKdpgkQ1pwNktQ5Lc19epBrzFjMUeNMUZGFvezFF2dX#z6MkveKdpgkQ1pwNktQ5Lc19epBrzFjMUeNMUZGFvezFF2dX",
"proofPurpose": "authentication",
"challenge": "QZVVFcXlMPStFmpXTSktv",
"domain": "https://unlinkable.example",
"proofValue": "z5tXmHk...x2GvTt3bF"
}
}
{ // external (all terms in this example)
"protected": {
"kid": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"alg": "EdDSA"
},
"payload": {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v4rc1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCardCredential"
],
"issuer": {
"id": "did:key:zUC7Do...oAVE",
"image": "data:image/png;base64,iVBORw0KGgoAA...CYII="
},
"name": "Permanent Resident Card",
"description": "Government of Utopia Permanent Resident Card.",
"credentialSubject": {
"type": [
"PermanentResident",
"Person"
],
"givenName": "JANE",
"familyName": "SMITH",
"gender": "Female",
"image": "data:image/png;base64,iVBORw0KGgoAAA...3dgg==",
"residentSince": "2015-01-01",
"commuterClassification": "C1",
"birthCountry": "Arcadia",
"birthDate": "1978-07-17",
"permanentResidentCard": {
"type": "PermanentResidentCard",
"identifier": "83627465",
"lprCategory": "C09",
"lprNumber": "999-999-999"
}
},
"validFrom": "2025-01-04T00:00:00Z",
"validUntil": "2026-01-04T23:59:59Z",
},
"signature": "qSv6d...bJRAw"
}
This section is non-normative.
These examples are for information purposes only, it is considered a best practice to avoid dislosing unnecessary information in JWE headers.
{ // external (all terms in this example)
"ciphertext": "3SHQQJajNH6q0fyAHmw...",
"iv": "QldSPLVnFf2-VXcNLza6mbylYwphW57Q",
"protected": "eyJlbmMiOiJYQzIwUCJ9",
"recipients": [
{
"encrypted_key": "BMJ19zK12YHftJ4sr6Pz1rX1HtYni_L9DZvO1cEZfRWDN2vXeOYlwA",
"header": {
"alg": "ECDH-ES+A256KW",
"apu": "Tx9qG69ZfodhRos-8qfhTPc6ZFnNUcgNDVdHqX1UR3s",
"apv": "ZGlkOmVsZW06cm9wc3RlbjpFa...",
"epk": {
"crv": "X25519",
"kty": "OKP",
"x": "Tx9qG69ZfodhRos-8qfhTPc6ZFnNUcgNDVdHqX1UR3s"
},
"kid": "did:example:123#zC1Rnuvw9rVa6E5TKF4uQVRuQuaCpVgB81Um2u17Fu7UK"
}
}
],
"tag": "xbfwwDkzOAJfSVem0jr1bA"
}
This section is non-normative.
This section is non-normative.
Following is a diagram showing the relationships among 4. Data Model , 5. Core Properties , and 7. Methods , and [ DID-RESOLUTION ].
This section is non-normative.
The
creation
of
a
DID
is
a
process
that
is
defined
by
each
DID
Method
.
Some
DID
Methods
,
such
as
did:key
,
are
purely
generative,
such
that
a
DID
and
a
DID
document
are
generated
by
transforming
a
single
piece
of
cryptographic
material
into
a
conformant
representation
.
Other
DID
methods
might
require
the
use
of
a
verifiable
data
registry
,
where
the
DID
and
DID
document
are
recognized
to
exist
by
third
parties
only
when
the
registration
has
been
completed,
as
defined
by
the
respective
DID
method
.
Other
processes
might
be
defined
by
the
respective
DID
method
.
This section is non-normative.
A DID is a specific type of URI (Uniform Resource Identifier), so a DID can refer to any resource. Per [ RFC3986 ]:
the term "resource" is used in a general sense for whatever might be identified by a URI. [...] A resource is not necessarily accessible via the Internet.
Resources can be digital or physical, abstract or concrete. Any resource that can be assigned a URI can be assigned a DID . The resource referred to by the DID is the DID subject .
The DID controller determines the DID subject . It is not expected to be possible to determine the DID subject from looking at the DID itself, as DIDs are generally only meaningful to machines, not human. A DID is unlikely to contain any information about the DID subject , so further information about the DID subject is only discoverable by resolving the DID to the DID document , obtaining a verifiable credential about the DID , or via some other description of the DID .
While
the
value
of
the
id
property
in
the
retrieved
DID
document
must
always
match
the
DID
being
resolved,
whether
or
not
the
actual
resource
to
which
the
DID
refers
can
change
over
time
is
dependent
upon
the
DID
method
.
For
example,
a
DID
method
that
permits
the
DID
subject
to
change
could
be
used
to
generate
a
DID
for
the
current
occupant
of
a
particular
role—such
as
the
CEO
of
a
company—where
the
actual
person
occupying
the
role
can
be
different
depending
on
when
the
DID
is
resolved.
This section is non-normative.
The DID refers to the DID subject and resolves to the DID document (by following the protocol specified by the DID method ). The DID document is not a separate resource from the DID subject and does not have a URI separate from the DID . Rather the DID document is an artifact of DID resolution controlled by the DID controller for the purpose of describing the DID subject .
This distinction is illustrated by the graph model shown below.
This section is non-normative.
Each property in a DID document is a statement by the DID controller that describes:
id
and
alsoKnownAs
properties)
verificationMethod
and
service
properties).
@context
property
for
a
JSON-LD
representation).
The
only
required
property
in
a
DID
document
is
id
,
so
that
is
the
only
statement
guaranteed
to
be
in
a
DID
document
.
That
statement
is
illustrated
in
Figure
5
with
a
direct
link
between
the
DID
and
the
DID
subject
.
This section is non-normative.
Options
for
discovering
more
information
about
the
DID
subject
depend
on
the
properties
present
in
the
DID
document
.
If
the
service
property
is
present,
more
information
can
be
requested
from
a
service
endpoint
.
For
example,
by
querying
a
service
endpoint
that
supports
verifiable
credentials
for
one
or
more
claims
(attributes)
describing
the
DID
subject
.
Another
option
is
to
use
the
alsoKnownAs
property
if
it
is
present
in
the
DID
document
.
The
DID
controller
can
use
it
to
provide
a
list
of
other
URIs
(including
other
DIDs
)
that
refer
to
the
same
DID
subject
.
Resolving
or
dereferencing
these
URIs
might
yield
other
descriptions
or
representations
of
the
DID
subject
as
illustrated
in
the
figure
below.
This section is non-normative.
If the DID subject is a digital resource that can be retrieved from the internet, a DID method can choose to construct a DID URL which returns a representation of the DID subject itself. For example, a data schema that needs a persistent, cryptographically verifiable identifier could be assigned a DID , and passing a specified Path or Query could be used as a standard way to retrieve a representation of that schema.
Similarly, a DID can be used to refer to a digital resource (such as an image) that can be returned directly from a verifiable data registry if that functionality is supported by the applicable DID method .
This section is non-normative.
If
the
controller
of
a
web
page
or
any
other
web
resource
wants
to
assign
it
a
persistent,
cryptographically
verifiable
identifier,
the
controller
can
give
it
a
DID
.
For
example,
the
author
of
a
blog
hosted
by
a
blog
hosting
company
(under
that
hosting
company's
domain)
could
create
a
DID
for
the
blog.
In
the
DID
document
,
the
author
can
include
the
alsoKnownAs
property
pointing
to
the
current
URL
of
the
blog,
e.g.:
"alsoKnownAs":
["https://myblog.blogging-host.example/home"]
If the author subsequently moves the blog to a different hosting company (or to the author's own domain), the author can update the DID document to point to the new URL for the blog, e.g.:
"alsoKnownAs":
["https://myblog.example/"]
The DID effectively adds a layer of indirection for the blog URL. This layer of indirection is under the control of the author instead of under the control of an external administrative authority such as the blog hosting company. This is how a DID can effectively function as an enhanced URN (Uniform Resource Name) —a persistent identifier for an information resource whose network location might change over time.
This section is non-normative.
To avoid confusion, it is helpful to classify DID subject s into two disjoint sets based on their relationship to the DID controller .
This section is non-normative.
The first case, shown in Figure 7 , is the common scenario where the DID subject is also the DID controller . This is the case when an individual or organization creates a DID to self-identify.
From a graph model perspective, even though the nodes identified as the DID controller and DID subject in Figure 7 are distinct, there is a logical arc connecting them to express a semantic equivalence relationship.
This section is non-normative.
The second case is when the DID subject is a separate entity from the DID controller . This is the case when, for example, a parent creates and maintains control of a DID for a child; a corporation creates and maintains control of a DID for a subsidiary; or a manufacturer creates and maintains control of a DID for a product, an IoT device, or a digital file.
From a graph model perspective, the only difference from Set 1 that there is no equivalence arc relationship between the DID subject and DID controller nodes.
This section is non-normative.
A DID document might have more than one DID controller . This can happen in one of two ways.
This section is non-normative.
In this case, each of the DID controllers might act on its own, i.e., each one has full power to update the DID document independently. From a graph model perspective, in this configuration:
This section is non-normative.
In the case of group control, the DID controllers are expected to act together in some fashion, such as when using a cryptographic algorithm that requires multiple digital signatures ("multi-sig") or a threshold number of digital signatures ("m-of-n"). These additional thresholds for verifying a proof can be expressed in a verification method as described in Section 5.2 Verification Methods or can be an intrinsic part of the verification material of the verification method , where the number of DID controllers that participated in the generation of a particular digital signature are hidden for privacy reasons. Verification methods that require a proof be produced by a combination of cryptographic operations performed by members of a group can be used to control the contents of a DID document; exactly how this is realized depends on individual DID method specifications.
From a functional standpoint, this option is similar to a single DID controller because, although each of the DID controllers in the DID controller group has its own graph node, the actual control collapses into a single logical graph node representing the DID controller group as shown in Figure 9 .
This configuration will often apply when the DID subject is an organization, corporation, government agency, community, or other group that is not controlled by a single individual.
This section is non-normative.
A
DID
document
has
exactly
one
DID
which
refers
to
the
DID
subject
.
The
DID
is
expressed
as
the
value
of
the
id
property.
This
property
value
is
immutable
for
the
lifetime
of
the
DID
document
.
However, it is possible that the resource identified by the DID , the DID subject , may change over time. This is under the exclusive authority of the DID controller . For more details, see section 8.11 Persistence .
This section is non-normative.
The DID controller for a DID document might change over time. However, depending on how it is implemented, a change in the DID controller might not be made apparent by changes to the DID document itself. For example, if the change is implemented through a shift in ownership of the underlying cryptographic keys or other controls used for one or more of the verification methods in the DID document , it might be indistinguishable from a standard key rotation.
On
the
other
hand,
if
the
change
is
implemented
by
changing
the
value
of
the
controller
property,
it
will
be
transparent.
If it is important to verify a change of DID controller , implementers are advised to authenticate the new DID controller against the verification methods in the revised DID document .
This section is non-normative.
This section contains the changes that have been made since the publication of this specification as a W3C First Public Working Draft.
Changes since the DID v1.0 Recommendation include:
application/did
after
IANA
registration
process
completed.
Changes since the DID v1.0 Second Candidate Recommendation include:
publicKeyMultibase
[
CID
].
Changes since the DID v1.0 First Candidate Recommendation include:
method-specific-id
ABNF
rule
and
for
nextUpdate
and
nextVersionId
.
equivalentId
and
canonicalId
are
optional.
publicKeyBase58
with
publicKeyMultibase
.
Changes since the DID v1.0 First Public Working Draft include:
This section is non-normative.
The Working Group extends deep appreciation and heartfelt thanks to our Chairs Brent Zundel and Dan Burnett, as well as our W3C Staff Contact, Ivan Herman, for their tireless work in keeping the Working Group headed in a productive direction and navigating the deep and dangerous waters of the standards process.
The Working Group gratefully acknowledges the work that led to the creation of this specification, and extends sincere appreciation to those individuals that worked on technologies and specifications that deeply influenced our work. In particular, this includes the work of Phil Zimmerman, Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw, and Rodney Thayer on Pretty Good Privacy (PGP) in the 1990s and 2000s.
In the mid-2010s, preliminary implementations of what would become Decentralized Identifiers were built in collaboration with Jeremie Miller's Telehash project and the W3C Web Payments Community Group's work led by Dave Longley and Manu Sporny. Around a year later, the XDI.org Registry Working Group began exploring decentralized technologies for replacing its existing identifier registry. Some of the first written papers exploring the concept of Decentralized Identifiers can be traced back to the first several Rebooting the Web of Trust workshops convened by Christopher Allen. That work led to a key collaboration between Christopher Allen, Drummond Reed, Les Chasen, Manu Sporny, and Anil John. Anil saw promise in the technology and allocated the initial set of government funding to explore the space. Without the support of Anil John and his guidance through the years, it is unlikely that Decentralized Identifiers would be where they are today. Further refinement at the Rebooting the Web of Trust workshops led to the first implementers documentation , edited by Drummond Reed, Les Chasen, Christopher Allen, and Ryan Grant. Contributors included Manu Sporny, Dave Longley, Jason Law, Daniel Hardman, Markus Sabadello, Christian Lundkvist, and Jonathan Endersby. This initial work was then merged into the W3C Credentials Community Group, incubated further, and then transitioned to the W3C Decentralized Identifiers Working Group for global standardization.
Portions of the work on this specification have been funded by the United States Department of Homeland Security's (US DHS) Science and Technology Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002, and HSHQDC-17-C-00019, as well as the US DHS Silicon Valley Innovation Program under contracts 70RSAT20T00000010, 70RSAT20T00000029, 70RSAT20T00000030, 70RSAT20T00000045, 70RSAT20T00000003, and 70RSAT20T00000033. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.
Portions of the work on this specification have also been funded by the European Union's StandICT.eu program under sub-grantee contract number CALL05/19. The content of this specification does not necessarily reflect the position or the policy of the European Union and no official endorsement should be inferred.
Work on this specification has also been supported by the Rebooting the Web of Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu Sporny, Drummond Reed, Joe Andrieu, and Heather Vescent. Development of this specification has also been supported by the W3C Credentials Community Group , which has been Chaired by Kim Hamilton Duffy, Joe Andrieu, Christopher Allen, Heather Vescent, and Wayne Chang. The participants in the Internet Identity Workshop, facilitated by Phil Windley, Kaliya Young, Doc Searls, and Heidi Nobantu Saul, also supported this work through numerous working sessions designed to debate, improve, and educate participants about this specification.
The
Working
Group
thanks
the
following
individuals
for
their
contributions
to
this
specification
(in
alphabetical
order,
Github
handles
start
with
@
and
are
sorted
as
last
names):
Denis
Ah-Kang,
Nacho
Alamillo,
Christopher
Allen,
Joe
Andrieu,
Antonio,
Phil
Archer,
George
Aristy,
Baha,
Juan
Benet,
BigBlueHat,
Dan
Bolser,
Chris
Boscolo,
Pelle
Braendgaard,
Daniel
Buchner,
Daniel
Burnett,
Juan
Caballero,
@cabo,
Tim
Cappalli,
Melvin
Carvalho,
David
Chadwick,
Wayne
Chang,
Sam
Curren,
Hai
Dang,
Tim
Daubenschütz,
Oskar
van
Deventer,
Kim
Hamilton
Duffy,
Arnaud
Durand,
Ken
Ebert,
Veikko
Eeva,
@ewagner70,
Carson
Farmer,
Nikos
Fotiou,
Gabe,
Gayan,
@gimly-jack,
@gjgd,
Ryan
Grant,
Peter
Grassberger,
Adrian
Gropper,
Amy
Guy,
Daniel
Hardman,
Kyle
Den
Hartog,
Philippe
Le
Hegaret,
Ivan
Herman,
Michael
Herman,
Alen
Horvat,
Dave
Huseby,
Marcel
Jackisch,
Mike
Jones,
Andrew
Jones,
Tom
Jones,
jonnycrunch,
Gregg
Kellogg,
Michael
Klein,
@kdenhartog-sybil1,
Paul
Knowles,
@ktobich,
David
I.
Lehn,
Charles
E.
Lehner,
Michael
Lodder,
@mooreT1881,
Dave
Longley,
Tobias
Looker,
Wolf
McNally,
Robert
Mitwicki,
Mircea
Nistor,
Grant
Noble,
Mark
Nottingham,
@oare,
Darrell
O'Donnell,
Vinod
Panicker,
Dirk
Porsche,
Praveen,
Mike
Prorock,
@pukkamustard,
Drummond
Reed,
Julian
Reschke,
Yancy
Ribbens,
Justin
Richer,
Rieks,
@rknobloch,
Mikeal
Rogers,
Evstifeev
Roman,
Troy
Ronda,
Leonard
Rosenthol,
Michael
Ruminer,
Markus
Sabadello,
Cihan
Saglam,
Samu,
Rob
Sanderson,
Wendy
Seltzer,
Mehran
Shakeri,
Jaehoon
(Ace)
Shim,
Samuel
Smith,
James
M
Snell,
SondreB,
Manu
Sporny,
@ssstolk,
Orie
Steele,
Shigeya
Suzuki,
Sammotic
Switchyarn,
@tahpot,
Oliver
Terbu,
Ted
Thibodeau
Jr.,
Joel
Thorstensson,
Tralcan,
Henry
Tsai,
Rod
Vagg,
Mike
Varley,
Kaliya
"Identity
Woman"
Young,
Eric
Welton,
Fuqiao
Xue,
@Yue,
Dmitri
Zagidulin,
@zhanb,
and
Brent
Zundel.
This section will be submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA when this specification becomes a W3C Proposed Recommendation.
Fragment identifiers used in JSON-LD environments are treated according to the rules associated with the JSON-LD 1.1: application/ld+json media type [ JSON-LD11 ]. Fragment identifiers used in JSON environments have the same semantic interpretation as those in JSON-LD environments. An algorithm for performing fragment resolution is provided in Section 3.4: Fragment Resolution of the Controlled Identifiers v1.0 specification which is extended by the Decentralized Identifiers (DIDs) v1.1 specification.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: