Decentralized Identifiers (DIDs) are a new type of identifier for verifiable, "self-sovereign" digital identity. DIDs are fully under the control of the DID subject, independent from any centralized registry, identity provider, or certificate authority. DIDs are URLs that relate a DID subject to means for trustable interactions with that subject. DIDs resolve to DID Documents — simple documents that describe how to use that specific DID. Each DID Document may contain at least three things: proof purposes, verification methods, and service endpoints. Proof purposes are combined with verification methods to provide mechanisms for proving things. For example, a DID Document can specify that a particular verification method, such as a cryptographic public key or pseudonymous biometric protocol, can be used to verify a proof that was created for the purpose of authentication. Service endpoints enable trusted interactions with the DID controller.

This document specifies a common data model, format, and operations that all DIDs support.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-credentials@w3.org ( subscribe, archives).

Portions of the work on this specification have been funded by the United States Department of Homeland Security's Science and Technology Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002 and HSHQDC-17-C-00019. 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.

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.

Introduction

Overview

Conventional identity management systems are based on centralized authorities such as corporate directory services, certificate authorities, or domain name registries. From the standpoint of cryptographic trust verification, each of these centralized authorities serves as its own root of trust. To make identity management work across these systems requires implementing federated identity management.

The emergence of distributed ledger technology (DLT), sometimes referred to as blockchain technology, provides the opportunity for fully decentralized identity management. In a decentralized identity system, entities (in the sense of discrete identifiable units such as—but not limited to—people and organisations) are free to use any shared root of trust. Globally distributed ledgers, decentralized P2P networks, or other systems with similar capabilities, provide the means for managing a root of trust with neither centralized authority nor a single point of failure. In combination, DLTs and decentralized identity systems enable any entity to create and manage their own identifiers on any number of distributed, independent roots of trust.

Entities are identified by decentralized identifiers (DIDs), and may authenticate via proofs (e.g., digital signatures, privacy-preserving biometric protocols, etc.). DIDs point to DID Documents. A DID Document contains a set of service endpoints for interacting with the entity the DID identifies (aka the DID subject). Following the dictums of Privacy by Design, any entity may have as many DIDs as necessary (and corresponding DID Documents and service endpoints), to respect the entity’s desired separation of identities, personas, and contexts.

DID methods are the mechanism by which a DID and its associated DID Document are created, read, updated, and deactivated on a specific distributed ledger or network. DID methods are defined using separate DID method specifications.

This design eliminates dependence on centralized registries for identifiers as well as centralized certificate authorities for key management—the standard pattern in hierarchical PKI (public key infrastructure). Because DIDs reside on a distributed ledger, each entity may serve as its own root authority—an architecture referred to as DPKI (decentralized PKI).

Note that DID methods may also be developed for identifiers registered in federated or centralized identity management systems. For their part, all types of identifier systems may add support for DIDs. This creates an interoperability bridge between the worlds of centralized, federated, and decentralized identifiers.

Motivations for DIDs

The growing need for decentralized identifiers has produced two specific requirements for a new type of URL that still fits Web Architecture and has a few additional requirements that more traditional URLs, like HTTP-based URLs, do not have:

  1. The new type of URL SHOULD NOT require a centralized authority to register, resolve or deactivate, nor to update associated data. The overwhelming majority of URIs today are based on DNS names or IP addresses that depend on centralized authorities for registration and ultimate control. DIDs can be created and managed without any such authority.
  2. A URL whose control and associated metadata, including public keys, can be cryptographically verified. Authentication via DIDs and DID Documents leverage the same public/private key cryptography as distributed ledgers.

The Role of Human-Friendly Identifiers

DIDs achieve global uniqueness without the need for a central registration authority. This comes, however, at the cost of human memorability. The algorithms capable of generating globally unique identifiers automatically produce random strings of characters that have no human meaning. This demonstrates the axiom about identifiers known as Zooko's Triangle: "human-meaningful, decentralized, secure—pick any two".

There are of course many use cases where it is desirable to discover a DID when starting from a human-friendly identifier—a natural language name, a domain name, or a conventional address for a DID controller such as a mobile telephone number, email address, Twitter handle, 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 out-of-scope for this specification.

Solutions to this problem (and there are many) should be defined in separate specifications that reference this specification. It is strongly recommended that such specifications carefully consider: (a) the numerous security attacks based on deceiving users about the true human-friendly identifier for a target entity, and (b) the privacy consequences of using human-friendly identifiers that are inherently correlatable, especially if they are globally unique.

Purpose of This Specification

The first purpose of this specification is to define the generic DID scheme and a generic set of operations on DID documents that can be implemented for any Decentralized Identifier Registry. The second purpose of this specification is to define the conformance requirements for a DID method specification—a separate specification that defines a specific DID scheme and specific set of DID document operations for a specific Decentralized Identifier Registry.

Conceptually, the relationship of this specification and a DID method specification is similar to the relationship of the IETF generic URI specification ([[RFC3986]]) and a specific URI scheme ([[IANA-URI-SCHEMES]] (such as the http: and https: schemes specified in [[RFC7230]]). It is also similar to the relationship of the IETF generic URN specification ([[RFC8141]]) and a specific URN namespace definition (such as the UUID URN namespace defined in [[RFC4122]]). The difference is that a DID method specification, in addition to defining a specific DID scheme, must also specify the methods for resolving and deactivating DIDs and writing DID documents on the network for which it is written.

For a list of DID Methods and their corresponding specifications, see the DID Method Registry [[DID-METHOD-REGISTRY]].

Design Goals

This section summarizes the design goals and principles of DID architecture.

Goal Description
Decentralization DID architecture should eliminate the requirement for centralized authorities or single points of failure in identifier management, including the registration of globally unique identifiers, public verification keys, service endpoints, and other metadata.
Self‑Sovereignty DID architecture should give entities, both human and non-human, the power to directly own and control their digital identifiers without the need to rely on external authorities.
Privacy DID architecture should enable entities to control the privacy of their information, including minimal, selective, and progressive disclosure of attributes or other data.
Security DID architecture should enable sufficient security for relying parties to depend on DID Documents for their required level of assurance.
Proof-based DID architecture should enable the DID subject to provide cryptographic proof of authentication and proof of authorization rights.
Discoverability DID architecture should make it possible for entities to discover DIDs for other entities to learn more about or interact with those entities.
Interoperability DID architecture should use interoperable standards so DID infrastructure can make use of existing tools and software libraries designed for interoperability.
Portability DID architecture should be system and network-independent and enable entities to use their digital identifiers with any system that supports DIDs and DID Methods.
Simplicity To meet these design goals, DID architecture should be (to paraphrase Albert Einstein) "as simple as possible but no simpler".
Extensibility When possible, DID architecture should enable extensibility provided it does not greatly hinder interoperability, portability, or simplicity.

Simple Examples

This is a simple example of a DID:

did:example:123456789abcdefghi
    

Self-Managed DID Document

Following is an example of a DID Document for the DID above. This example assumes that the subject of the DID Document is the controller of the private keys for this identifier.

{
  "@context": "https://w3id.org/did/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    // this key can be used to authenticate as did:...fghi
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [{
    "id": "did:example:123456789abcdefghi#service123",
    "type": "ExampleService",
    "serviceEndpoint": "https://example.com/endpoint/8377464"
  }]
}
      

Terminology

Data Model

This section outlines the Decentralized Identifier data model concepts. These are elaborated in .

Document

Keys

Services

Decentralized Identifiers (DIDs)

The concept of a globally unique decentralized identifier is not new; Universally Unique Identifiers (UUIDs) were first developed in the 1980s and later became a standard feature of the Open Software Foundation’s Distributed Computing Environment. UUIDs achieve global uniqueness without a centralized registry service by using an algorithm that generates 128-bit values with sufficient entropy that the chance of collision are infinitesimally small. UUIDs are formally specified in [[RFC4122]] as a specific type of Unified Resource Name (URN).

A DID is similar to a UUID except: (a) like a URL, it can be resolved or dereferenced to a standard resource describing the subject (a DID Document—see Section ), and (b) unlike a URL, the DID Document typically contains cryptographic material that enables authentication of the DID subject.

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 term DID refers only to the URI conforming to the did rule in the ABNF below. A DID always identifies the DID subject. The term DID URL, defined by the did-url rule, refers to a URL that begins with a DID followed by one or more additional components. A DID URL always identifies the resource to be located.

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

The grammar currently allows an empty method-specific-id, e.g. did:example: would be a valid DID that could identify the DID method itself.

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 .

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 .

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

Generic DID Parameter Name Description

The exact processing rules for these parameters are specified in the DID Resolution specification.

Note that there may be additional parameters or options that are not part of the DID URL but instead passed to a DID resolver “out of band”, i.e., using a resolution protocol or some other mechanism. Such options could for example control caching or the desired format of a resolution result. This is similar to HTTP, where caching or result format are expressed as HTTP headers rather than as part of an HTTP URL. The important distinction is that DID parameters that are part of the DID URL specify what resource is being identified, whereas DID resolver options that are not part of the DID URL control how that resource is dereferenced.

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

Consider using kebab-case style instead of colon separator, e.g. foo-bar instead of foo:bar.

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

Review what exactly we want to say about method-specific parameters defined by one method but used in a DID URL with a different method. Also discuss hierarchical method namespaces in DID parameter names.

Path

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

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

Query

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

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

Fragment

A generic DID fragment is identical to a URI fragment and MUST conform to the the fragment ABNF rule in [[RFC3986]]. A DID fragment MUST be used only as a method-independent reference into the DID Document to identify a component of a DID Document (e.g. a unique key description). To resolve this reference, the complete DID URL including the DID fragment MUST be used as the value of the key 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]]).

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 MUST be defined by the governing DID method specification.

Persistence

A DID MUST be persistent and immutable, i.e., bound to the subject 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 Decentralized Identifier Registries over time, thus maintaining its persistence independent of any particular system. However registering the same identifier on multiple Decentralized Identifier 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 Decentralized Identifier Registries capable of making the highest level of commitment to persistence of the DID and DID method over time.

Although not included in this version, future versions of this specification may support a DID Document equivID property to establish verifiable equivalence relations between DIDs representing the same subject on multiple Decentralized Identifier Registries. Such equivalence relations can produce the practical equivalent of a single persistent abstract DID. See Future Work (Section ).

DID Documents

A DID points to a DID Document. DID Documents are the serialization of the . The following sections define the properties of the DID Document, including whether these properties are required or optional.

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://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.

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 Decentralized Identifier Registry, the registered DID MUST match this DID subject value.

Example:

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

DID Method specifications MAY create intermediate representations of a DID Document that do not contain the id key, such as when a DID Resolver is performing resolution. However, the fully resolved DID Document MUST contain a valid id property.

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 ) or establishing secure communication with service endpoints (see Section ). In addition, public keys may play a role in authorization mechanisms of DID CRUD operations (see Section ). 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 controller of 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 .

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.

While the controller field may seem redundant in some of the examples above, keys may be expressed in a DID Document where the controller is described in another DID Document. Linked Data Proof libraries typically expect the controller field to always exist and may throw an exception if it is missing. Futhermore, per the requirement that DID Documents be interpretable as either a graph or a tree, a default controller field cannot be inferred by using a key's position in a tree.

Caching and expiration of the keys in a DID Document is entirely the responsibility of DID resolvers and other clients. See Section .

Authentication

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

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 ).

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"
    }
  ],
  ...
}

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 . 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 .

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, Delegation, and the concept of Guardianship:

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

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": "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 and for further security considerations regarding authentication service endpoints.

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

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 .

Example:

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

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 , 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 . 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=="
  }
}

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:

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 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.

DID Document Syntax

A DID Document MUST be a single JSON object conforming to [[RFC8259]]. Many of the concepts in this document were introduced by example using the JSON-LD syntax, a format for mapping JSON data into the RDF semantic graph model as defined by [[!JSON-LD]]. This section formalizes how the data model (described in Sections and ) is realized in JSON-LD.

Although syntactic mappings are provided for JSON and JSON-LD only, applications and services can use any other data representation syntax, such as JXD (JSON XDI Data, a serialization format for the XDI graph model), XML, YAML, or CBOR, that is capable of expressing the data model.

JSON

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

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 ), 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 .

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:

DID Methods

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 ).

Since DIDs are intended for decentralized identity infrastructure, it is NOT RECOMMENDED to establish a definitive software 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. To facilitate this, we maintain a document listing known DID method names and their associated specifications (see Appendix ).

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 Decentralized Identifier 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 fully qualified DID as defined by the DID rule in Section 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.

DID Operations

To enable the full functionality of DIDs and DID Documents on a particular Decentralized Identifier 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. 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.:

Create

The DID method specification MUST specify how a client creates a DID and its associated DID Document on the Decentralized Identifier Registry, including all cryptographic operations necessary to establish proof of control.

Read/Verify

The DID method specification MUST specify how a client uses a DID to request a DID Document from the Decentralized Identifier Registry, including how the client can verify the authenticity of the response.

Update

The DID method specification MUST specify how a client can update a DID Document on the Decentralized Identifier Registry, including all cryptographic operations necessary to establish proof of control.

Deactivate

Although a core feature of distributed ledgers is immutability, the DID method specification MUST specify how a client can deactivate a DID on the Decentralized Identifier Registry, including all cryptographic operations necessary to establish proof of deactivation.

DID Resolvers

A DID resolver is a software component with an API designed to accept requests for DID lookups and execute the corresponding DID method to retrieve the authoritative DID Document. To be conformant with this specification, a DID resolver:

  1. SHOULD validate that a DID is valid according to its DID method specification, otherwise it should produce an error.
  2. MUST conform to the requirements of the applicable DID method specification when performing DID resolution operations.
  3. SHOULD offer the service of verifying the integrity of the DID Document if it is signed.
  4. MAY offer the service of returning requested properties of the DID Document.

Security Considerations

NOTE TO IMPLEMENTERS: During the Implementer’s Draft stage, this section focuses on security topics that should be important in early implementations. The editors are also seeking feedback on threats and threat mitigations that should be reflected in this section or elsewhere in the spec. As the root identifier records for decentralized identifiers, DIDs and DID Documents are a vital component of decentralized identity management. They are also the foundational building blocks of DPKI (decentralized public key infrastructure) as an augmentation to conventional X.509 certificates. As such, DIDs are designed to operate under the general Internet threat model used by many IETF standards. We assume uncompromised endpoints, but allow messages to be read or corrupted on the network. Protecting against an attack when a system is compromised requires external key-signing hardware. See also section regarding key revocation and recovery. For their part, the DLTs hosting DIDs and DID Documents have special security properties for preventing active attacks. Their design uses public/private key cryptography to allow operation on passively monitored networks without risking compromise of private keys. This is what makes DID architecture and decentralized identity possible.

Requirements of DID Method Specifications

  1. DID method specifications MUST include their own Security Considerations sections.
  2. This section MUST consider all the requirements mentioned in section 5 of [[RFC3552]] (page 27) for the DID operations defined in the specification. In particular:

Discussions at Rebooting the Web of Trust 5 resulted in consensus to move Authorization to DID Method specifications. It is currently expected that there will be an attempt to create a generalized authorization mechanism that is build on object capabilities.

At least the following forms of attack MUST be considered: eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle. Potential denial of service attacks MUST be identified as well. If the protocol incorporates cryptographic protection mechanisms, it should be clearly indicated which portions of the data are protected and what the protections are (i.e., integrity only, confidentiality, and/or endpoint authentication, etc.). Some indication should also be given to what sorts of attacks the cryptographic protection is susceptible. Data which should be held secret (keying material, random seeds, etc.) should be clearly labeled. If the technology involves authentication, particularly user-host authentication, the security of the authentication method MUST be clearly specified.

  1. This section MUST also discuss, per Section 5 of [[RFC3552]], residual risks (such as the risks from compromise in a related protocol, incorrect implementation, or cipher) after threat mitigation has been deployed.
  2. This section MUST provide integrity protection and update authentication for all operations required by Section 7 of this specification (DID Operations).
  3. Where DID methods make use of peer-to-peer computing resources (such as with all known DLTs), the expected burdens of those resources SHOULD be discussed in relation to denial of service.
  4. Method-specific endpoint authentication MUST be discussed. Where DID methods make use of DLTs with varying network topology, sometimes offered as "light node" or “ thin client ” implementations to reduce required computing resources, the security assumptions of the topology available to implementations of the DID method MUST be discussed.
  5. DID methods MUST discuss the policy mechanism by which DIDs are proven to be uniquely assigned. A DID fits the functional definition of a URN as defined in [[RFC8141]]—a persistent identifier that is assigned once to a resource and never reassigned. In a security context this is particularly important since a DID may be used to identify a specific party subject to a specific set of authorization rights.
  6. DID methods that introduce new authentication service endpoint types (Section ) SHOULD consider the security requirements of the supported authentication protocol.

Binding of Identity

Proving Control of a DID and DID Document

Signatures are one method to allow DID Documents to be cryptographically verifiable.

By itself, a verified signature on a self-signed DID Document does not prove control of a DID. It only proves the following:

  1. The DID Document has not been tampered with since it was registered.
  2. The controller of the DID Document controlled the private key used for the signature at the time the signature was generated.

Proving control of a DID, i.e., the binding between the DID and the DID Document that describes it, requires a two step process:

  1. Resolving the DID to a DID Document according to its DID method specification.
  2. Verifying that the id property of the resulting DID Document matches the DID that was resolved.

It should be noted that this process proves control of a DID and DID Document regardless of whether the DID Document is signed.

Signatures on DID Documents are optional. DID Method Specs SHOULD explain and specify their implementation if applicable.

It is RECOMMENDED to combine timestamps with signatures.

Proving Control of a Public Key

There are two methods for proving control of the private key corresponding to a public key description in the DID Document: static and dynamic. The static method is to sign the DID Document with the private key. This proves control of the private key at a time no later than the DID Document was registered. If the DID Document is not signed, control of a public key described in the DID Document may still be proven dynamically as follows:

  1. Send a challenge message containing a public key description from the DID Document and a nonce to an appropriate service endpoint described in the DID Document.
  2. Verify the signature of the response message against the public key description.

Authentication and Verifiable Claims

A DID and DID Document do not inherently carry any PII (personally-identifiable information). The process of binding a DID to something in the real-world such as a person or company, for example with credentials with the same subject as that DID, is out of scope for this specification. However this topic is the focus of the verifiable claims standardization work at the W3C (where the term "DID" originated).

Authentication Service Endpoints

If a DID Document publishes a service endpoint intended for authentication or authorization of the subject (section ), it is the responsibility of the service endpoint provider, subject, and/or relying party to comply with the requirements of the authentication protocol(s) supported at that service endpoint.

Non-Repudiation

Non-repudiation of DIDs and DID Document updates is supported under the assumption that: (1) the subject is monitoring for unauthorized updates (see Section ) and (2) the subject has had adequate opportunity to revert malicious updates according to the DID method's access control mechanism (section ). This capability is further supported if timestamps are included (sections and ) and the target DLT system supports timestamps.

Notification of DID Document Changes

One mitigation against unauthorized changes to a DID Document is monitoring and actively notifying the 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, where there is no intermediary registrar or account provider to generate the notification, the following approaches are RECOMMENDED:

  1. Subscriptions. If the Decentralized Identifier Registry on which the DID is registered directly supports change notifications, this service can be offered to DID controllers. Notifications may be sent directly to the relevant service endpoints listed in an existing DID.
  2. Self-monitoring. A DID subject may employ their own local or online agent to periodically monitor for changes to a DID Document.
  3. Third-party monitoring. A DID subject may rely on a third party monitoring service, however this introduces another vector of attack.

Key and Signature Expiration

In a decentralized identifier architecture, there are no centralized authorities to enforce key or signature expiration policies. Therefore DID resolvers and other client applications SHOULD validate that keys were not expired at the time they were used. Since some use cases may have legitimate reasons why already-expired keys can be extended, a key expiration SHOULD NOT prevent any further use of the key, and implementations of a resolver SHOULD be compatible with such extension behavior.

Key Revocation and Recovery

Section specifies the DID operations that must be supported by a DID method specification, including deactivation of a DID Document by replacing it with an updated DID Document. In general, checking for key revocation on DLT-based methods is expected to be handled in a manner similar to checking the balance of a cryptocurrency account on a distributed ledger: if the balance is empty, the entire DID is deactivated. DID method specifications SHOULD enable support for a quorum of trusted parties to enable key recovery. Some of the facilities to do so are suggested in section 6.5, Authorization. Note that not all DID method specifications will recognize control from DIDs registered using other DID methods and they MAY restrict third-party control to DIDs that use the same method. Access control and key recovery in a DID method specification MAY also include a time lock feature to protect against key compromise by maintaining a second track of control for recovery. Further specification of this type of control is a matter for future work (see section ).

Privacy Considerations

It is critically important to apply the principles of Privacy by Design to all aspects of decentralized identifier architecture, because DIDs and DID Documents are—by design—administered directly by their controllers. There is no registrar, hosting company, or other intermediate service provider to recommend or apply additional privacy safeguards. The authors of this specification have applied all seven Privacy by Design principles throughout its development. For example, privacy in this specification is preventative not remedial, and privacy is an embedded default. Furthermore, decentralized identifier architecture by itself embodies principle #7, "Respect for user privacy—keep it user-centric." This section lists additional privacy considerations that implementers, delegates, and DID subjects should bear in mind.

Requirements of DID Method Specifications

  1. DID method specifications MUST include their own Privacy Considerations sections, if only to point to the general privacy considerations in this section.
  2. The DID method privacy section MUST discuss any subsection of section 5 of [[RFC6973]] that could apply in a method-specific manner. The subsections to consider are: surveillance, stored data compromise, unsolicited traffic, misattribution, correlation, identification, secondary use, disclosure, exclusion.

Keep Personally-Identifiable Information (PII) Private

If a DID method specification is written for a public Decentralized Identifier Registry where all DIDs and DID Documents will be publicly available, it is STRONGLY RECOMMENDED that DID Documents contain no PII. All PII should be kept behind service endpoints under the control of the subject. With this privacy architecture, PII may be exchanged on a private, peer-to-peer basis using communications channels identified and secured by key descriptions in DID documents. This also enables subjects and relying parties to implement the GDPR right to be forgotten, as no PII will be written to an immutable ledger.

DID Correlation Risks and Pseudonymous DIDs

Like any type of globally unique identifier, DIDs may be used for correlation. DID controllers can mitigate this privacy risk by using pairwise unique DIDs, i.e., by sharing a different private DID for every relationship. In effect, each DID acts as a pseudonym. A pseudonymous DID need only be shared with more than one party when the subject explicitly authorizes correlation between those parties. If pseudonymous DIDs are the default, then the only need for a public DID—a DID published openly or shared with a large number of parties—is when the subject explicitly desires public identification.

DID Document Correlation Risks

The anti-correlation protections of pseudonymous DIDs are easily defeated if the data in the corresponding DID Documents can be correlated. For example, using same public key descriptions or bespoke service endpoints in multiple DID Documents can provide as much correlation information as using the same DID. Therefore the DID Document for a pseudonymous DID SHOULD also use pairwise-unique public keys. It might seem natural to also use pairwise-unique service endpoints in the DID Document for a pseudonymous DID. However, unique endpoints allow all traffic between to DIDs to be isolated perfectly into unique buckets, where timing correlation and similar analysis is easy. Therefore, a better strategy for endpoint privacy may be to share an endpoint among thousands or millions of DIDs controlled by many different subjects.

Herd Privacy

When a DID subject is indistinguishable from others in the herd, 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 SHOULD work to improve herd privacy, particularly for those who legitimately need it most. Choose technologies and human interfaces that default to preserving anonymity and pseudonymity. In order to reduce digital fingerprints, share common settings across client implementations, keep negotiated options to a minimum on wire protocols, use encrypted transport layers, and pad messages to standard lengths.

Future Work

Upper Limits on DID Character Length

The current specification does not take a position on maximum length of a DID. The maximum interoperable URL length is currently about 2K characters. QR codes can handle about 4K characters. Clients using DIDs will be responsible for storing many DIDs, and some methods would be able to externalize some of their costs onto clients by relying on more complicated signature schemes or by adding state into DIDs intended for temporary use. A future version of this specification should set reasonable limits on DID character length to minimize externalities.

Equivalence

Including an equivalence property, such as equivID, in DID Documents whose value is an array of DIDs would allow subjects to assert two or more DIDs that represent the same subject. This capability has numerous uses, including supporting migration between Decentralized Identifier Registries and providing forward compatibility of existing DIDs to future Decentralized Identifier Registries. In theory, equivalent DIDs should have the same identifier rights, allowing verifiable claims made against one DID to apply to equivalent DIDs. Equivalence was not included in the current specification due to the complexity of verifying equivalence across different DLTs and different DID methods, and also of aggregating properties of equivalent DID Documents. However equivalence should be supported in a future version of this specification.

Timestamps

Verifiable timestamps have significant utility for identifier records. This is a good fit for DLTs, since most offer some type of timestamp mechanism. Despite some transactional cost, they are the most censorship-resistant transaction ordering systems in the world, so they are nearly ideal for DID Document timestamping. In some cases a DLT's immediate timing is approximate, however their sense of "median time past" (see Bitcoin BIP 113) can be precisely defined. A generic DID Document timestamping mechanism could would work across all DLTs and might operate via a mechanism including either individual transactions or transaction batches. The generic mechanism was deemed out of scope for this version, although it may be included in a future version of this specification.

Time Locks and DID Document Recovery

Section mentions one possible clever use of time locks to recover control of a DID after a key compromise. The technique relies on an ability to override the most recent update to a DID Document with Authorization applied by an earlier version of the DID Document in order to defeat the attacker. This protection depends on adding a time lock (see Bitcoin BIP 65) to protect part of the transaction chain, enabling a Authorization block to be used to recover control. We plan to add support for time locks in a future version of this specification.

Smart Signatures

Not all DLTs can support the Authorization logic in section 6.5. Therefore, in this version of the specification, all Authorization logic must be delegated to DID method specifications. A potential future solution is a Smart Signature specification that specifies the code any conformant DLT may implement to process signature control logic.

Verifiable Claims

Although DIDs and DID Documents form a foundation for decentralized identity, they are only the first step in describing a their subjects. The rest of the descriptive power comes through collecting and selectively using verifiable claims. Future versions of the specification will describe in more detail how DIDs and DID Document can be integrated with—and help enable—the verifiable claims ecosystem.

Alternate Serializations and Graph Models

This version of the specification relies on JSON-LD and the RDF graph model for expressing a DID Document. Future versions of this specification MAY specify other semantic graph formats for a DID Document, such as JXD (JSON XDI Data), a serialization format for the XDI graph model as defined by the OASIS XDI Core 1.0 specification.

Registries

There are multiple registries that define DID Methods and extensions to this specification. These registries are:

Registry Purpose
DID Method Registry Defines all known DID Methods and contains links to their specifications.
Linked Data Cryptography Suite Registry Defines all known Linked Data Cryptography Suites and Key Formats.

Real World Example

A future-facing real-world context is provided below:

{
  "@context": "https://w3id.org/future-method/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-3",
    "type": "Ieee2410VerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],

  "authentication": [
    // this mechanism can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this mechanism can be used to biometrically authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-3",
    // this mechanism 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"
    }
  ],

  "service": [{
    "id": "did:example:123456789abcdefghi#oidc",
    "type": "OpenIdConnectVersion1.0Service",
    "serviceEndpoint": "https://openid.example.com/"
  }, {
    "id": "did:example:123456789abcdefghi#vcStore",
    "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#hub",
    "type": "HubService",
    "serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
  }, {
    "id": "did:example:123456789abcdefghi#messaging",
    "type": "MessagingService",
    "serviceEndpoint": "https://example.com/messages/8377464"
  }, {
    "type": "SocialWebInboxService",
    "id": "did:example:123456789abcdefghi#inbox",
    "serviceEndpoint": "https://social.example.com/83hfh37dj",
    "description": "My public social inbox",
    "spamCost": {
      "amount": "0.50",
      "currency": "USD"
    }
  }, {
    "type": "DidAuthPushModeVersion1",
    "id": "did:example:123456789abcdefghi#push",
    "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefghi"
  }, {
    "id": "did:example:123456789abcdefghi#bops",
    "type": "BopsService",
    "serviceEndpoint": "https://bops.example.com/enterprise/"
  }]
}