Decentralized Identifiers (DIDs) v0.13

4.1 Generic DID Syntax

The generic DID scheme is a URI scheme conformant with [RFC3986]. The DID scheme specializes only the scheme and authority components of a DID URI — the path-abempty, query, and fragment components are identical to the ABNF rules defined in [RFC3986].

The following is the ABNF definition using the syntax in [RFC5234] which defines ALPHA and DIGIT. All other rule names not defined in this ABNF are defined in [RFC3986].

did                = "did:" method-name ":" method-specific-id
method-name        = 1*method-char
method-char        = %x61-7A / DIGIT
method-specific-id = *idchar *( ":" *idchar )
idchar             = ALPHA / DIGIT / "." / "-" / "_"
did-url            = did *( ";" param ) path-abempty [ "?" query ]
                     [ "#" fragment ]
param              = param-name [ "=" param-value ]
param-name         = 1*param-char
param-value        = *param-char
param-char         = ALPHA / DIGIT / "." / "-" / "_" / ":" /
                     pct-encoded

4.2 Method-Specific Syntax

A DID method specification MUST further restrict the generic DID syntax by defining its own method-name and its own method-specific-id syntax. See Section § 7. DID Methods .

4.3 Generic DID Parameter Names

DID URL syntax supports a simple, generalized format for parameters based on the matrix parameter syntax ([MATRIX-URIS]). The ABNF above does not specify any parameter names (the param-name rule).

Some generic DID parameter names (e.g., for service selection) are completely independent of any specific DID method and MUST always function the same way for all DIDs. Others (e.g., for versioning) MAY be supported by certain DID methods, but MUST operate uniformly across those DID methods that do support them.

Parameter names that are completely method-specific are covered in § 4.4 Method-Specific DID Parameter Names .

The following table defines a set of generic DID parameter names:

The exact processing rules for these parameters are specified in [DID-RESOLUTION].

4.4 Method-Specific DID Parameter Names

A DID method specification MAY specify additional method-specific parameter names. A method-specific parameter name MUST be prefixed by the method name as defined by the method-name rule.

For example, if the method did:foo: defines the parameter bar, the parameter name must be foo:bar. An example DID URL using this method and this method-specific parameter would be:

did:foo:21tDAKCERh95uGgKbJNHYp;foo:bar=high

A method-specific parameter name defined by one DID method MAY be used by other DID methods. For example:

did:example:21tDAKCERh95uGgKbJNHYp;foo:bar=low

Method-specific parameter names MAY be combined with generic parameter names in any order.

did:example:21tDAKCERh95uGgKbJNHYp;service=agent;foo:bar=high

Both DID method namespaces and method-specific parameter namespaces MAY include colons, so they may be partitioned hierarchically as defined by a DID method specification. Here is an example DID URL that illustrates both:

did:foo:baz:21tDAKCERh95uGgKbJNHYp;foo:baz:hex=b612

4.5 Path

A generic DID path is identical to a URI path and MUST conform to the path-abempty ABNF rule in [RFC3986]. A DID path SHOULD be used to address resources available via a DID service endpoint. See Section § 5.6 Service Endpoints .

A specific DID scheme MAY specify ABNF rules for DID paths that are more restrictive than the generic rules in this section.

did:example:123456/path

4.6 Query

A generic DID query is identical to a URI query and MUST conform to the query ABNF rule in [RFC3986]. A DID query SHOULD be used to address resources available via a DID service endpoint. See Section § 5.6 Service Endpoints .

A specific DID scheme MAY specify ABNF rules for DID queries that are more restrictive than the generic rules in this section.

did:example:123456?query=true

4.7 Fragment

A generic DID fragment is identical to a URI fragment and MUST conform to the fragment ABNF rule in [RFC3986]. Implementers are strongly discouraged from using a DID fragment for anything other than a method-independent reference into the DID Document to identify a component of a DID Document (e.g. a unique key description or service endpoint). To resolve this reference, the complete DID URL including the DID fragment MUST be used as input to the DID URL dereferencing algorithm (see [DID-RESOLUTION]) for the target component in the DID Document object.

A specific DID scheme MAY specify ABNF rules for DID fragments that are more restrictive than the generic rules in this section.

It is desirable that we enable tree-based processing of DIDs that include DID fragments (which resolve directly within the DID Document) to locate metadata contained directly in the DID Document or the service resource given by the target URL without needing to rely on graph-based processing.

Implementations SHOULD NOT prevent the use of JSON pointers ([RFC6901]).

did:example:123456#oidc

4.8 Normalization

For the broadest interoperability, DID normalization should be as simple and universal as possible. Therefore:

1. The did: scheme name MUST be lowercase.
2. The method name MUST be lowercase.
3. Case sensitivity and normalization of the value of the method-specific-id rule in Section §  4.1 Generic DID Syntax MUST be defined by the governing DID method specification.

4.9 Persistence

A DID is expected to be persistent and immutable, i.e., bound exclusively and permanently to its one and only subject. Even after a DID has been deactivated, it is intended that it never be repurposed.

Ideally a DID would be a completely abstract decentralized identifier (like a UUID) that could be bound to multiple underlying DID Registries over time, thus maintaining its persistence independent of any particular system. However registering the same identifier on multiple DID Registries introduces extremely hard entityship and start-of-authority (SOA) problems. It also greatly increases implementation complexity for developers.

To avoid these issues, it is RECOMMENDED that DID method specifications only produce DIDs and DID methods bound to strong, stable DID Registries capable of making the highest level of commitment to persistence of the DID and DID method over time.

5.1 Contexts

When two software systems need to exchange data, they must use terminology and a protocol that both systems understand. As an analogy, consider how two people communicate. Both people must use the same language and the words they use must mean the same thing to each other. This specification uses the @context property to express the context of a conversation.

@context

The value of the @context property MUST be one or more URIs, where the value of the first URI is https://www.w3.org/2019/did/v1. If more than one URI is provided, the URIs MUST be interpreted as an ordered set. It is RECOMMENDED that dereferencing the URIs results in a document containing machine-readable information about the context.

DID Documents MUST include the @context property. The JSON-LD Context is described in detail in the [JSON-LD] specification. The rules for this statement are:

1. A DID Document MUST have exactly one top-level context statement.
2. The key for this property MUST be @context.
3. The value of this key MUST be the URL for the generic DID context: https://www.w3.org/2019/did/v1.

Example (using an example URL):

{
  "@context": "https://www.w3.org/2019/did/v1"
}

DID method specifications MAY define their own JSON-LD contexts. However it is NOT RECOMMENDED to define a new context unless necessary to properly implement the method. Method-specific contexts MUST NOT override the terms defined in the generic DID context.

5.2 DID Subject

The DID Subject is the entity that the DID Document is about, i.e., it is the entity identified by the DID and described by the DID Document. The rules for a DID subject are:

1. A DID Document MUST have exactly one DID subject.
2. The key for this property MUST be id.
3. The value of this key MUST be a valid DID.
4. When this DID Document is registered with the target DID Registry, the registered DID MUST match this DID subject value.

Example:

{
  "id": "did:example:21tDAKCERh95uGgKbJNHYp"
}

5.3 Public Keys

Public keys are used for digital signatures, encryption and other cryptographic operations, which in turn are the basis for purposes such as authentication (see Section § 5.4 Authentication ) or establishing secure communication with service endpoints (see Section § 5.6 Service Endpoints ). In addition, public keys may play a role in authorization mechanisms of DID CRUD operations (see Section § 7.2 DID Operations ). This may be defined by DID Method specifications.

If a public key does not exist in the DID Document, it MUST be assumed the key has been revoked or is invalid. The DID Document MAY contain revoked keys. A DID Document that contains a revoked key MUST also contain or refer to the revocation information for the key (e.g., a revocation list). Each DID Method specification is expected to detail how revocation is performed and tracked.

The rules for public keys are:

1. A DID Document MAY include a publicKey property.
2. The value of the publicKey property MUST be an array of public keys, and every public key property MUST be in the Linked Data Cryptographic Suite Registry.
3. Each public key MUST include id and type properties, and exactly one value property. The array of public keys MUST NOT contain duplicate entries with the same id.
4. Each public key MUST include a controller property, which identifies the controller of the corresponding private key.
5. A registry of key types and formats is available in Appendix § A. Registries .

Example:

{
  "@context": ["https://www.w3.org/2019/did/v1", "https://w3id.org/security/v1"],
  "id": "did:example:123456789abcdefghi",
  ...
  "publicKey": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }, {
    "id": "did:example:123456789abcdefghi#keys-2",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:pqrstuvwxyz0987654321",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }, {
    "id": "did:example:123456789abcdefghi#keys-3",
    "type": "Secp256k1VerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71"
  }],
  ...
}

A key MAY be embedded or referenced in a DID Document. For example, the authentication property may refer to keys in both ways:

{
...

  "authentication": [
    // this key is referenced, it may be used for more than one proof purpose
    "did:example:123456789abcdefghi#keys-1",
    // this key is embedded and may *only* be used for authentication
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],

...
}

The algorithm to use when processing a publicKey property in a DID Document is:

1. Let value be the data associated with the publicKey property and initialize result to null.
2. If value is an object, the key material is embedded. Set result to value.
3. If value is a string, the key is included by reference. Assume value is a URL.
   1. Dereference the URL and retrieve the publicKey properties associated with the URL (e.g., process the publicKey property at the top-level of the dereferenced document).
   2. Iterate through each public key object.
      1. If the id property of the object matches value, set result to the object.
4. If result does not contain at least the id, type, and controller properties as well as any mandatory public cryptographic material, as determined by the result's type property, throw an error.

5.4 Authentication

Authentication is the mechanism by which the controller(s) of a DID can cryptographically prove that they are associated with that DID. See Section § 9.3 Binding of Identity . Note that Authentication is separate from Authorization because the controllers may wish to enable others to update their DID Document (for example, to assist with key recovery as discussed in Section § 9.8 Key Revocation and Recovery ) without enabling them to prove control (and thus be able to impersonate the controllers).

The rules for Authentication are:

1. A DID Document MAY include an authentication property.
2. The value of the authentication property SHOULD be an array of verification methods.
3. Each verification method MAY be embedded or referenced. An example of a verification method is a public key (see Section § 5.3 Public Keys ).

Example:

{
  "@context": "https://www.w3.org/2019/did/v1",
  "id": "did:example:123456789abcdefghi",
  ...
  "authentication": [
    // this method can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#biometric-1",
    // this method is *only* authorized for authentication, it may not
    // be used for any other proof purpose, so its full description is
    // embedded here rather than using only a reference
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}

5.5 Authorization and Delegation

Authorization is the mechanism used to state how operations may be performed on behalf of the DID subject. Delegation is the mechanism that the subject may use to authorize others to act on their behalf. Note that Authorization is separate from Authentication as explained in Section § 5.4 Authentication . This is particularly important for key recovery in the case of key loss, when the subject no longer has access to their keys, or key compromise, where the controller’s trusted third parties need to override malicious activity by an attacker. See Section § 9. Security Considerations .

Each DID Method MUST define how authorization and delegation are implemented, including any necessary cryptographic operations.

There are at least two suggested methods for implementing Authorization and Delegation, which may be layered:

1. A DID Registry could implement a coarse grained controller pattern by enabling DID Documents to express the DID of another DID controller that controls it, or additionally,
2. A DID Registry could implement a Capabilities-based approach that enables further fine-grained control of authorization and delegation.

Example:

{
  "@context": "https://www.w3.org/2019/did/v1",
  "id": "did:example:123456789abcdefghi",
  "controller": "did:example:bcehfew7h32f32h7af3",
  "service": [{
    // used to retrieve Verifiable Credentials associated with the DID
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}

5.6 Service Endpoints

In addition to publication of authentication and authorization mechanisms, the other primary purpose of a DID Document is to enable discovery of service endpoints for the subject. A service endpoint MAY represent any type of service the subject wishes to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction. The rules for service endpoints are:

1. A DID Document MAY include a service property.
2. The value of the service property SHOULD be an array of service endpoints.
3. Each service endpoint MUST include id, type, and serviceEndpoint properties, and MAY include additional properties.
4. The service endpoint protocol SHOULD be published in an open standard specification.
5. The value of the serviceEndpoint property MUST be a JSON-LD object or a valid URI conforming to [RFC3986] and normalized according to the rules in section 6 of [RFC3986] and to any normalization rules in its applicable URI scheme specification.

Example:

{
  "service": [{
    "id": "did:example:123456789abcdefghi#openid",
    "type": "OpenIdConnectVersion1.0Service",
    "serviceEndpoint": "https://openid.example.com/"
  }, {
    "id": "did:example:123456789abcdefghi#vcr",
    "type": "CredentialRepositoryService",
    "serviceEndpoint": "https://repository.example.com/service/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#xdi",
    "type": "XdiService",
    "serviceEndpoint": "https://xdi.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#agent",
    "type": "AgentService",
    "serviceEndpoint": "https://agent.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#hub",
    "type": "IdentityHub",
    "publicKey": "did:example:123456789abcdefghi#key-1",
    "serviceEndpoint": {
      "@context": "https://schema.identity.foundation/hub",
      "type": "UserHubEndpoint",
      "instances": ["did:example:456", "did:example:789"]
    }
  }, {
    "id": "did:example:123456789abcdefghi#messages",
    "type": "MessagingService",
    "serviceEndpoint": "https://example.com/messages/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#inbox",
    "type": "SocialWebInboxService",
    "serviceEndpoint": "https://social.example.com/83hfh37dj",
    "description": "My public social inbox",
    "spamCost": {
      "amount": "0.50",
      "currency": "USD"
    }
  }, {
    "id": "did:example:123456789abcdefghi#authpush",
    "type": "DidAuthPushModeVersion1",
    "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg"
  }]
}

See Sections § 7.1 DID Method Schemes and § 5.4 Authentication for further security considerations regarding authentication service endpoints.

5.7 Created (Optional)

Standard metadata for identifier records includes a timestamp of the original creation. The rules for including a creation timestamp are:

1. A DID Document MUST have zero or one property representing a creation timestamp. It is RECOMMENDED to include this property.
2. The key for this property MUST be created.
3. The value of this key MUST be a valid XML datetime value as defined in section 3.3.7 of W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes [XMLSCHEMA11-2].
4. This datetime value MUST be normalized to UTC 00:00 as indicated by the trailing "Z".
5. Method specifications that rely on DLTs SHOULD require time values that are after the known "median time past" (defined in Bitcoin BIP 113), when the DLT supports such a notion.

Example:

{
  "created": "2002-10-10T17:00:00Z"
}

5.8 Updated (Optional)

Standard metadata for identifier records includes a timestamp of the most recent change. The rules for including an updated timestamp are:

1. A DID Document MUST have zero or one property representing an updated timestamp. It is RECOMMENDED to include this property.
2. The key for this property MUST be updated.
3. The value of this key MUST follow the formatting rules (3, 4, 5) from Section § 5.7 Created (Optional) .

Example:

{
  "updated": "2016-10-17T02:41:00Z"
}

5.9 Proof (Optional)

A proof on a DID Document is cryptographic proof of the integrity of the DID Document according to either:

1. The subject as defined in Section § 5.2 DID Subject , or:
2. The controller as defined in Section § 5.5 Authorization and Delegation , if present.

This proof is NOT proof of the binding between a DID and a DID Document. See Section § 9.3 Binding of Identity . The rules for a proof are:

1. A DID Document MAY have exactly one property representing a proof.
2. The key for this property MUST be proof.
3. The value of this key MUST be a valid JSON-LD proof as defined by Linked Data Proofs.

Example:

{
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2016-02-08T16:02:20Z",
    "creator": "did:example:8uQhQMGzWxR8vw5P3UWH1ja#keys-1",
    "signatureValue": "QNB13Y7Q9...1tzjn4w=="
  }
}

5.10 Extensibility

One of the goals of the Decentralized Identifiers Data Model is to enable permissionless innovation. This requires that the data model is extensible in a number of different ways:

• The requirement to model complex multi-entity relationships is provided through the use of a graph-based data model.
• The requirement to enable extending the machine-readable vocabularies used to describe information in the data model — without relying on a centralized system — is accomplished via the use of [LINKED-DATA].
• The requirement to support multiple types of cryptographic proof formats is accomplished via the use of Linked Data Proofs [LD-PROOFS], Linked Data Signatures [LD-SIGNATURES], and a variety of signature suites.
• The requirement to provide all of the extensibility mechanisms outlined above in a data format that is popular among software developers and web page authors is enabled via the use of [JSON-LD].

This approach to data modeling is often called an "open world assumption", meaning that anyone can say anything about any other thing. This approach often feels in conflict with building simple and predictable software systems. Balancing extensibility with program correctness is always more challenging with an open world assumption than it is with closed software systems.

The rest of this section describes how both extensibility and program correctness are achieved through a series of examples.

Let us assume that we start with the following DID Document:

{
  "@context": "https://example.org/example-method/v1",
  "id": "did:example:123456789abcdefghi",
  "publicKey": [{ ... }],
  "authentication": [{ ... }],
  "service": [{ ... }]
}

The contents of the publicKey, authentication, and service properties are not important for the purposes of this section. What is important is that the object above is a valid DID Document. Let's assume that a developer wanted to extend the DID Document to express an additional piece of information: the subject's public photo stream.

The first thing that a developer would do is create a JSON-LD Context containing the new term:

{
  "@context": {
    "PhotoStreamService": "https://example.com/vocab#PhotoStreamService"
  }
}

Now that the JSON-LD Context has been created, the developer MUST publish it somewhere that is accessible to any DID Document processor. For this example, let us assume that the JSON-LD Context above is published at the following URL: did:example:contexts:987654321. At this point, extending the first example in this section is a simple matter of including the context above and adding the new property to the DID Document.

{
  "@context": "https://example.org/example-method/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [ ... ],
  "service": [{
    "@context": "did:example:contexts:987654321",
    "id": "did:example:123456789abcdefghi#photos",
    "type": "PhotoStreamService",
    "serviceEndpoint": "https://example.org/photos/379283"
  }]
}

The examples so far have shown that it is easy to extend the Decentralized Identifiers Data Model in a permissionless and decentralized way. The mechanism also ensures that Decentralized Identifiers created in this way prevent namespace conflicts and semantic ambiguity.

An extensibility model that is this dynamic does increase implementation burden. Software written for such a system will have to determine if accepting DID Documents with extensions is acceptable based on the risk profile of the application. Some applications may choose to accept but ignore extensions, others may choose to only accept certain extensions, while highly secure environments may disallow extensions. These decisions are up to the application developers and are specifically not the domain of this specification.

Implementations MUST produce an error when an extension JSON-LD Context overrides the expanded URL for a term specified in this specification. To avoid the possibility of accidentally overriding terms, developers SHOULD scope their extensions. For example, the following extension scopes the new PhotoStreamService term so that it may only be used within the service property:

{
  "@context": {
    "service": {
      "@id": "https://w3id.org/did#service",
      "@context": {
        "PhotoStreamService": "https://example.com/vocab#PhotoStreamService"
      }
    }
  }
}

Developers are urged to ensure that extension JSON-LD Contexts are highly available. Implementations that cannot fetch a context will produce an error. Strategies for ensuring that extension JSON-LD Contexts are always available include using content-addressed URLs for contexts, bundling context documents with implementations, or enabling aggressive caching of contexts.

6.1 JSON

The data model as described in Section § 3. Data Model can be encoded in Javascript Object Notation (JSON) [RFC8259] by mapping property values to JSON types as follows:

• Numeric values representable as IEEE754 SHOULD be represented as a Number type.
• Boolean values SHOULD be represented as a Boolean type.
• Sequence value SHOULD be represented as an Array type.
• Unordered sets of values SHOULD be represented as an Array type.
• Sets of properties SHOULD be represented as an Object type.
• Empty values SHOULD be represented as a null value.
• Other values MUST be represented as a String type.

6.2 JSON-LD

[JSON-LD] is a JSON-based format used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems already using JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily intended to be a way to use Linked Data in Web-based programming environments, to build interoperable Web services, and to store Linked Data in JSON-based storage engines.

JSON-LD is useful when extending the data model described in this specification. Instances of the data model are encoded in JSON-LD in the same way they are encoded in JSON (Section § 6.1 JSON), with the addition of the @context property. The JSON-LD Context is described in detail in the [JSON-LD] specification and its use is elaborated on in Section § 5.10 Extensibility .

In general, the data model and syntaxes described in this document are designed such that developers can copy and paste examples into their software systems. The design goal of this approach is to provide a low barrier to entry while still ensuring global interoperability between a heterogeneous set of software systems. This section describes some of these approaches, which will likely go unnoticed by most developers, but whose details will be of interest to implementers. The most noteworthy syntactic sugars provided by JSON-LD are:

• The @id and @type keywords are aliased to id and type respectively, enabling developers to use this specification as idiomatic JSON.
• Data types, such as integers, dates, units of measure, and URLs, are automatically typed to provide stronger type guarantees for use cases that require them.
• The @protected properties feature of JSON-LD 1.1 is used to ensure that terms defined by this specification cannot be overridden. This means that as long as the same @context declaration is made at the top of a DID Document, that interoperability is guaranteed between implementations which use a JSON-LD processor and implementations which do not.

7.1 DID Method Schemes

A DID method specification MUST define exactly one specific DID scheme identified by exactly one method name (the method-name rule in Section § 4.1 Generic DID Syntax ).

Since the method name is part of the DID, it SHOULD be as short as practical. A method name of five characters or less is RECOMMENDED. The method name MAY reflect the name of the DID Registry to which the DID method specification applies.

The DID method specification for the specific DID scheme MUST specify how to generate the method-specific-id component of a DID. The method-specific-id value MUST be able to be generated without the use of a centralized registry service. The method-specific-id value SHOULD be globally unique by itself. The DID as defined by the did rule in Section § 4.1 Generic DID Syntax MUST be globally unique.

If needed, a specific DID scheme MAY define multiple specific method-specific-id formats. It is RECOMMENDED that a specific DID scheme define as few method-specific-id formats as possible.

7.2 DID Operations

To enable the full functionality of DIDs and DID Documents on a particular DID Registry, a DID method specification MUST specify how each of the following CRUD operations is performed by a client. Each operation MUST be specified to the level of detail necessary to build and test interoperable client implementations with the target system. The specification document for a DID method that does not support specific operations such as Update and Deactivate MUST clearly specify these limitations. Note that, due to the specified contents of DID Documents, these operations can effectively be used to perform all the operations required of a CKMS (cryptographic key management system), e.g.:

• Key registration
• Key replacement
• Key rotation
• Key recovery
• Key expiration