Decentralized Identifiers

Decentralized identifiers are one of the foundational ideas for supporting self-sovereign identity. This post describes how decentralized identifiers work.

Decentralized identifiers are one of several foundational technologies for building a metasystem for self-sovereign identity. I wrote about verifiable credentials and their exchange previously. Just like the Web required not only URLs, but also a specification for web page formats and how web pages could be formatted, self-sovereign identity needs DIDs, a protocol for creating DID-based relationships, and a specification and protocol for verifiable credential exchange.

Identifiers label things. Computer systems are full of identifiers. Variable names are identifiers. Usernames are identifiers. Filenames are identifiers. IP numbers are identifiers. Domain names are identifiers. Email addresses are identifiers. URLs are identifiers. [1] Any time we use a unique (within some context) string to label something for quick reference, we’re giving it an identifier. A computer system uses identifiers to correlate all the information it knows about a given thing. The mis-use of identifiers can lead to unwanted, even dangerous correlations.

Identifiers need context to be meaningful. For example, a string of digits might be a phone number, but we have no way of knowing for sure without context. Online context is often provided by a prefix. For example, is an email address, but is an account identifier.

Web-based identity systems have largely defaulted to using email addresses as identifiers. Everyone has one. And someone else has done the work of ensuring uniqueness since email addresses must be globally unique. But email addresses are also less than ideal as identifiers for several reasons:

  1. First, email addresses have a real, intended use (sending email) and so might change for reasons unrelated to their use as an identifier.

Decentralized Identifiers

Decentralized Identifiers, or DIDs, are a new kind of identifier that solves the problems outlined in the last section. As noted above, DIDs are one of the foundational technologies of self-sovereign identity. The DIDs specification is being developed inside the W3C Credentials Community Group. Let’s explore the properties of DIDs and look at how they are formatted.

DID Properties

Decentralized identifiers should be implemented so that they have these important properties:

  • non-reassignable-DIDs should be permanent, persistent, and non-reassignable. Permanence ensures that the identifier always references the same entity. As a result, DIDs are more private and more secure than identifiers that can be reassigned such as a domain name, IP address, email address, or mobile number. Permanence is vital for user control and self sovereignty.

DID Syntax

The syntax of a DID is fairly simple and designed to support different decentralization methods. The following diagram shows the primary, required components of a DID:

Each component is separated by a colon. The scheme, did, is fixed for all DIDs and alerts software seeing the DID that it is a DID. The method specifies how the DID is created, updated, and resolved. In the preceding figure, the method is sov. The method-specific identifier is an alphanumeric string that is guaranteed to be unique within the context of the method.

DID Resolution

Useful identifiers have a means of discovering what the identifier means. Discovery is performed in the manner outlined in the DID method. The DID specification outlines the necessary operations any method must implement. Different methods can support their own way of performing resolution using a specific blockchain or other storage system. The method outlines the way to create, retrieve, and update the DID and it’s associate DID Document. For example, the did:sov method outlines how to create, lookup, and update the DID on the Sovrin ledger. A resolver can use the method to find the routines necessary for interacting with a given identifier. Methods allow a variety of systems to serve as repositories for DIDs.

DIDs are resolved to a DID Document. Resolution is the act of looking up the DID Document for a specific DID using the method given by the DID’s method component. Taken as a whole, DID infrastructure functions as a global, decentralized key-value store where DIDs act as the keys and DID Documents are the values.

While the expectation is that these repositories will be decentralized, there’s nothing in the specification that forces that. Any storage system could potentially have a DID method associated with it. Beware that some repositories may not be able to fulfill the non-reuse and permanence properties that are expected of DIDs.

DID Documents

DID Documents describe the public keys, authentication protocols, and service endpoints necessary to initiate trustworthy interactions with the identified entity. A DID Document is a JSON-LD document that contain the following six, optional components:

  1. The DID that points to the DID Document, identified by the key id.

DID Documents can use other JSON-LD contexts to extend the DID Document and aid in discovery. For example, the data model could be extended to include the entity’s RSS feed by referencing a JSON-LD context that describes RSS feeds.

The following is an example of a minimal DID Document taken from the DID specification [2]:

"@context": "",
"id": "did:sov:123456789abcdefghij",
"publicKey": [{
"id": "did:sov:123456789abcdefghij#keys-1",
"type": "RsaVerificationKey2018",
"controller": "did:sov:123456789abcdefghij",
"publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
"authentication": [{
"type": "RsaSignatureAuthentication2018",
"publicKey": "did:sov:123456789abcdefghi#keys-1"
"service": [{
"id": "did:sov:123456789abcdefghij;exam_svc",
"type": "ExampleService",
"serviceEndpoint": ""
"created": "2018-02-08T16:03:00Z",
"proof": {
"type": "LinkedDataSignature2015",
"created": "2018-02-08T16:02:20Z",
"creator": "did:sov:8uQhQMGzWxR8vw5P3UWH1ja#keys-1",
"signatureValue": "QNB13Y7Q9...1tzjn4w=="

The DID Document is the root record for a decentralized identifier that can reference not only what’s in the DID Document itself, but also any information from the service endpoints. This is accomplished by adding selectors, paths, query parameters, and fragments to the DID. With the exception of selectors, which are specific to DIDs, the syntax of these is familiar to anyone acquainted with the syntax of a URI.

The selector is used to identify a particular part of the DID Document. Selectors follow the DID itself and are delineated with a semicolon. In the preceding DID Document, there is only one service. Nevertheless, it can be selected using the following DID:


If the DID also includes a path, that is appended to the URL given in the service’s serviceEndpoint attribute before the endpoint is called. For example, the following DID:


is equivalent to the following URL:

Through this mechanism, DIDs provide a permanent, resolvable identifier for any Internet service. For example, If one of the service endpoints in my DID Document is for email, then I can change my email address at will and anyone holding that DID will still be able to reach me. All I need to do is to be sure to update the DID Document when I change my email.

Public and Private DIDs

The preceding use case-putting my email in a DID Document-might be a privacy problem if I don’t want my email to be publicly readable. Fortunately, not all DIDs are public. Identifiers can be, in the language of Kim Cameron (PDF), omnidirectional or unidirectional. Kim says in reference to his fourth law, Directed Identity:

A universal identity system must support both “omnidirectional” identifiers for use by public entities and “unidirectional” identifiers for use by private entities, thus facilitating discovery while preventing unnecessary release of correlation handles.

Sovrin supports public DIDs, written to the ledger and resolvable by all-omnidirectional identifiers. Sovrin also supports private DIDs, exchanged between parties to a relationship and resolvable only within that relationship-unidirectional identifiers.

The availability of private DIDs has significant advantages. Practically speaking, private DIDs allow for greater scalability of the DID resolution infrastructure since the vast majority of DIDs are private and those are resolved on a peer-to-peer basis rather than through access to some shared piece of infrastructure such as a distributed ledger.

More importantly, as Kim says about directed identity, private DIDs reduce access to correlatable identifiers by third parties increasing privacy protections. Private DIDs are critical infrastructure for a key part of the Sovrin architecture: peer relationships.

Peer Relationships

In On Sovereignty, I write:

The key to sovereignty is that all entities are peers. I have the same rights you do. The beauty of sovereignty isn’t complete and total control, but rather balance of power that leads to negotiations about the nature of the relationships between various entities in the system.

In a world of identity systems based on decentralized identifiers, people do not create accounts at online service providers and then merely exist within that administrative system. Rather, people create relationships with other online entities and relate as peers.

To see how this works, imagine that you have recently been hired at a new job. Your new employer, ACME Corp, has a public DID that they use for issuing verifiable credentials. But as part of your employee onboarding, they and you will each create and exchange private DIDs. Because DIDs are cryptographically verifiable, you now each have a secure, channel to the other. You can use these DIDs to mutually authenticate when a connection is established, and to encrypt your communications.

This DID-based peer relationship is based on software agents that act for each party, maintain DIDs, resolve them, and facilitate cryptographically secure communication. The connection is truly peer-to-peer without some other platform in the middle. Apps and services built on top of these peer relationships can use these secure communication channels without being party to the private keys that secure them and ensure their integrity.

Since a DID Doc is JSON-LD and can be extended with other contexts, it can be extended to include other information. For example, you could extend the DID Document you share with your employer to include your home address and bank account information. Whenever those change, you’d update that DID Document and your employer would automatically see the changes.

Since the DID with selectors, fragments, and paths provides a way to resolve this information at will, the employer could merely store DIDs for that information rather than the information itself and resolve it at the local agent each time it is needed. Anyone breaking into their systems and stealing the reference wouldn’t have permission to resolve the reference and get sensitive information. This provides the means for an employee, say, to share information with an employer that can be trusted and resolved at will without the employee having to issue a verifiable credential.

DIDs and the Identity Metasystem

In The Laws of Identity, I make the case for Sovrin being an identity metasystem-a universal foundation upon which other identity systems can be built. DIDs and DID Documents are a big part of the metasystem. Sovrin is designed to support the use of DIDs and DID Documents. Furthermore, Sovrin agents manage DID-based peer relationships, verifiable credential exchange, public and private DID resolution, and DID-based secure communication and authentication. DIDs allow Sovrin to be used by multiple parties for their own purposes.

Online Sovereignty

Decentralized identifiers and the attendant infrastructure that supports them provide a significant improvement over the ad hoc, email, and domain name based identifiers we’ve used for identity systems in the past. DIDs represent a universal addressing, abstraction, and verification layer for key pairs, endpoints, and any other information we wish to include in the DID Document. Layer verifiable credential exchange on top of this for multi-source identity and this constitutes a significant upgrade to online identity.

Because there’s no central authority controlling DIDs and because people can issue private DIDs themselves, they constitute a truly decentralized means of not only creating identifiers, but using them for mutual authentication, privacy preservation, and secure communication of almost any information parties need to share.

Speaking of DIDs, DID Documents, and Verifiable Credentials in an email to Project VRM mailing list, Joe Andrieu, put it like this:

The win is that these new technologies let us engage in digital society with identifiers we create and control — rather than those gifted or rented to us from a third party. Combined with an open system of verifiable attributes, we can also control the selective disclosure of certain “provable” assertions (provable in the sense that some entity like the DMV stands behind the assertion). Collectively, the identifiers and attributes constitute a full and verifiable identity in the common sense we imagine. For the first time, we can come to the party as a peer of the realm instead of a serf.

An identity metasystem that can provide real peer relationships is critical to protecting individual privacy, creating real security, and, more importantly, supporting human dignity. DIDs are a key part of the architecture.


  1. All of these may be other things as well like addresses or names, but they’re still identifiers.

Photo Credit: Grey Color Keychain Mat Metal Key Shiny from Unknown (CC0 Public Domain)

Originally published at

I build things; I write code; I void warranties