Decentralized Identifiers (DIDs) v1.0

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 URL — 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 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 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 public 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.

Implementations need not rely on graph-based processing of DID documents to locate metadata contained in the DID document when the DID includes a DID fragment. Tree-based processing can be used instead.

Implementations SHOULD NOT prevent the use of JSON Pointer ([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 need to use terminology and a protocol that both systems understand. The @context property ensures that two systems operating on the same DID document are using mutually agreed terminology.

DID documents MUST include the @context property.

@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/ns/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.

Example:

{
  "@context": "https://www.w3.org/ns/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 denoted with the id property. This 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.

DID documents MUST include the id property.

id

The value of id MUST be a single valid DID.

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 ), which can be defined by DID method specifications.

A DID document MAY include a publicKey property. If so:

publicKey

The value of the publicKey property MUST be an array of public key objects. Each public key object MUST have the type, controller, and specific public key properties, and SHOULD have an id property. The object MAY include additional properties.

The value of the id property (if present) MUST be a URI. The array of public keys MUST NOT contain multiple entries with the same id. A DID document processor MUST produce an error in that case.

The value of the type property MUST be exactly one public key value (see available key types in Appendix § B. Registries ).

The value of the controller property, which identifies the controller of the corresponding private key, MUST be a valid DID.

All public key properties MUST be from the Linked Data Cryptographic Suite Registry. A registry of key types and formats is available in Appendix § B. Registries

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.

Example:

{
  "@context": ["https://www.w3.org/ns/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 DID controllers can cryptographically prove that they are associated with a DID. For more information, see Section § 9.3 Binding of Identity . Note that Authentication is separate from Authorization because DID controllers might 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 DID controller(s)).

A DID document MAY include an authentication property. If so:

authentication

The value of the authentication property SHOULD be an array of verification methods. 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/ns/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 uses 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 DID 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/ns/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

One of the primary purposes of a DID document is to enable discovery of service endpoints. A service endpoint can be any type of service the DID subject wishes to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction.

A DID document MAY include a service property. If so:

service

The value of the service property SHOULD be an array of service endpoint objects. Each service endpoint MUST have type and serviceEndpoint properties, SHOULD have an id property, and MAY include additional properties.

The value of the id property (if present) MUST be a URI. The array of service endpoints MUST NOT contain multiple entries with the same id. A DID document processor MUST produce an error in that case.

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.

It is expected that the service endpoint protocol is published in an open standard 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

A DID document SHOULD include a created property. If so:

created

The value of created 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]. This datetime value MUST be normalized to UTC 00:00 as indicated by the trailing "Z".

Example:

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

5.8 Updated

Standard metadata for identifier records includes a timestamp of the most recent change.

A DID document SHOULD include an updated property. If so:

updated

The updated value MUST follow the same formatting rules as the created property (see Section § 5.7 Created ).

Example:

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

5.9 Proof

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

1. The DID subject as defined in Section § 5.2 DID Subject , or:
2. The DID 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 ).

A DID document MAY include a proof property. If so:

proof

The value of proof 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. Noteworthy features 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.