Decentralized Identifiers (DIDs) v0.11

4.2.1 DID Fragments

A generic DID fragment (the did-fragment rule in Section § 4.2 DID Reference) is identical to a URI fragment and MUST conform to the ABNF of the fragment ABNF rule in [RFC3986]. A DID fragment MUST be used only as a method-independent pointer into the DID Document to identify a unique key description or other DID Document component. To resolve this pointer, the complete DID reference including the DID fragment MUST be used as the value of the id key for the target JSON 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]).

4.2.2 DID Reference Service Paths, Queries, and Fragments

A DID Reference service path (the service-path rule in Section § 4.2 DID Reference) is identical to a URI path and MUST conform to the ABNF of the path-rootless ABNF rule in [RFC3986]. The path is used to address resources available via a DID service endpoint. See Section § 4.3.6 Service Endpoints.

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

The DID Reference service query and service fragment (the service-query and service-fragment rules in Section § 4.2 DID Reference) parts are identical to their URI counterparts and MUST conform to the ABNF of the query and fragment rules in [RFC3986].

4.2.3 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-idstring rule in Section § 4.1 The Generic DID Scheme MUST be defined by the governing DID method specification.

4.2.4 Persistence

A DID MUST be persistent and immutable, i.e., bound to an entity once and never changed (forever).

Ideally a DID would be a completely abstract decentralized identifier (like a UUID) that could be bound to multiple underlying distributed ledgers or networks over time, thus maintaining its persistence independent of any particular ledger or network. However registering the same identifier on multiple ledgers or networks 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 ledgers or networks capable of making the highest level of commitment to persistence of the DID and DID method over time.

4.3.1 Context

JSON objects in JSON-LD format must include a JSON-LD context statement. 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://w3id.org/did/v1.

Example (using an example URL):

{
  "@context": "https://w3id.org/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.

4.3.2 DID Subject

The DID subject is the identifier that the DID Document is about, i.e., it is the DID described by 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 distributed ledger or network, the registered DID MUST match this DID subject value.

Example:

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

4.3.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 § 4.3.4 Authentication) or establishing secure communication with service endpoints (see Section § 4.3.6 Service Endpoints). In addition, public keys may play a role in authorization mechanisms of DID CRUD operations (see Section § 4.4.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.
3. Each public key MUST include id and type properties, and exactly one value property. The array of public keys SHOULD NOT contain duplicate entries with the same id and different value properties with different formats.
4. Each public key MUST include a controller property, which identifies the entity that controls the corresponding private key.
5. The value property of a public key MUST be exactly one of publicKeyPem, publicKeyJwk, publicKeyHex, publicKeyBase64, publicKeyBase58, publicKeyMultibase, depending on the format and encoding of the public key.
6. A registry of key types and formats is available in Appendix § 4.9 Registries.

Example:

{
  "@context": ["https://w3id.org/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.

4.3.4 Authentication

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

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 § 4.3.3 Public Keys).

Example:

{
  "@context": "https://w3id.org/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"
    }
  ],
  ...
}

4.3.5 Authorization and Delegation

Authorization is the mechanism by which an entity states how one may perform operations on behalf of the entity. Delegation is the mechanism that an entity may use to authorize other entities to act on its behalf. Note that Authorization is separate from Authentication as explained in Section § 4.3.4 Authentication. This is particularly important for key recovery in the case of key loss, when the entity 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 § 4.6 Security Considerations.

Since Authorization and Delegation are typically implemented by the ledger, each DID Method specification is expected to detail how authorization and delegation are performed for the ledger.

There are at least two suggested methods for implementing Authorization, Delegation, and the concept of Guardianship:

1. A ledger could implement a coarse grained guardian pattern by reusing the same proof purpose pattern used by the authentication property, or more preferably
2. A ledger could implement a Capabilities-based approach and provide more fine-grained control of authorization, delegation, and guardianship.

4.3.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 entity. A service endpoint may represent any type of service the entity 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": "HubService",
    "serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
  }, {
    "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 § 4.4.1 DID Method Schemes and § 4.3.4 Authentication for further security considerations regarding authentication service endpoints.

4.3.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"
}

4.3.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 § 4.3.7 Created (Optional).

Example:

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

4.3.9 Proof (Optional)

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

1. The entity as defined in section § 4.3.6 Service Endpoints, or if not present:
2. The delegate as defined in section 4.3.

This proof is NOT proof of the binding between a DID and a DID Document. See Section § 4.6.2 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=="
  }
}

4.3.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 any entity can say anything about any other entity. 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 in the decentralized ledger 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 are urged to 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.

4.4.1 DID Method Schemes

A DID method specification MUST define exactly one specific DID scheme identified by exactly one method name (the method rule in Section § 4.1 The Generic DID Scheme). Since DIDs are intended for decentralized identity infrastructure, it is NOT RECOMMENDED to establish a registry of unique DID method names. Rather the uniqueness of DID method names should be established via human consensus, i.e., a specific DID scheme MUST use a method name that is unique among all DID method names known to the specification authors at the time of publication.

A list of known DID method names and their associated specifications is provided in Appendix § 4.9 Registries.

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 distributed ledger or network to which the DID method specification applies.

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

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

4.4.2 DID Operations

To enable the full functionality of DIDs and DID Documents on a particular distributed ledger or network (called the target system), 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. 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