DID Document

4 min read

Pronunciation

[ˌdē-ˌī-ˈdē ˈdä-kyə-mənt]

Analogy

Think of a DID Document like a sophisticated, self-updating business card that contains not just contact information, but also cryptographic credentials proving it's authentic. Just as a business card might list different ways to contact someone (phone, email, office ), a DID Document lists different ways to interact with a digital identity (authentication keys, service endpoints, verification methods). However, unlike a static business card that anyone could potentially forge, a DID Document includes cryptographic proofs making it tamper-evident and verifiable—similar to how a holographic government ID contains security features proving its authenticity. Additionally, while a traditional business card is created by a printing company according to your specifications, a DID Document is created and updated directly by the identity's controller without requiring permission from any central authority—fundamentally changing the power relationship from one of dependency to one of autonomy in how digital identities are established and maintained.

Definition

A machine-readable document containing metadata associated with a Decentralized Identifier (DID), specifying verification methods, service endpoints, and controller information that enables interactions with the identified entity. DID Documents function as the public-facing interface for decentralized identities, providing the cryptographic material and service information necessary for authentication, authorization, and communication while maintaining the identifier owner's privacy and autonomy.

Key Points Intro

DID Documents enable decentralized identity through four core components:

Key Points

Verification Methods: Define the cryptographic material (like public keys) that can be used to authenticate the DID subject or verify claims related to the identity.

Service Endpoints: Specify the network locations where interactions with the identity can occur, such as data exchange, credential issuance, or messaging services.

Controller Information: Indicates which entities have administrative rights to make changes to the DID Document, establishing governance for the identifier.

Proof Mechanisms: Include cryptographic evidence verifying the document's integrity and authenticity, ensuring it hasn't been tampered with since authorized updates.

Example

A developer creates a professional DID to represent her online identity across various web3 applications and services. The resulting DID Document, accessible at did:ion:abc123...xyz, contains multiple verification methods: an Ed25519 key for general authentication, a key specifically for transactions, and a capability invocation method enabling delegated actions under specific constraints. The document lists several service endpoints, including her personal API for receiving encrypted messages, a verification service for checking her published code signatures, and a credential exchange endpoint for professional certifications. Controller information specifies that changes to the document require cryptographic signatures from both her primary device and a separate hardware security key, implementing two-factor control. When she applies for a remote development position, she authenticates to the company's hiring portal using her DID. The portal retrieves her DID Document, verifies her authentication proof against the specified verification methods, and uses the service endpoints to request verified credentials attesting to her development experience—all without requiring a centralized identity provider or sharing unnecessary personal data. When she later adds a new device, she updates her DID Document to include additional authentication methods, maintaining persistent identity across changing technical implementations.

Technical Deep Dive

DID Documents implement sophisticated data structures conforming to the W3C Decentralized Identifier specification, typically expressed in JSON-LD format to support semantic interoperability while maintaining extensibility. The core document structure includes mandatory elements like the DID itself ('id') and controller information ('controller'), along with arrays of verification methods, services, and relationship definitions. Verification methods within the document specify cryptographic material using standardized representations. These typically include 'id' (a unique identifier for the method), 'type' (the cryptographic algorithm used), 'controller' (the DID that controls this method), and 'publicKeyMultibase' or equivalent (the actual cryptographic material encoded in a multiformat representation). Advanced implementations support various key types including Ed25519, , , and emerging -quantum algorithms. Service endpoints follow a similar structure with 'id', 'type', and 'serviceEndpoint' fields. The type field references standardized service definitions like DIDCommMessaging, VerifiableCredentialService, or LinkedDomains, enabling consistent discovery and interaction patterns across different DID methods. Service endpoints may include additional properties specific to each service type, such as requirements or API version information. For relationship definitions, DID Documents establish explicit connections between the DID subject and verification methods for specific purposes. These include 'authentication' (methods that can prove control of the DID), 'assertionMethod' (methods that can make claims on behalf of the subject), 'keyAgreement' (methods for establishing encrypted communications), and 'capabilityInvocation' (methods authorized to exercise capabilities granted to the DID). Document representation typically employs content-addressed storage techniques, often using cryptographic hashes as identifiers for specific document versions. This enables secure referencing and verification of document integrity throughout its lifecycle. Advanced implementations support additional features like service type registries for extensibility, proof formats for document verification, and also-known-as properties for correlating identifiers across different systems.

Security Warning

DID Documents serve as the foundation for identity security in decentralized systems, making their integrity critical. Verify that resolution mechanisms properly validate the provenance and update history of documents, particularly for unfamiliar DID methods that might have unique security characteristics. Be cautious about employing verification methods or services listed in a DID Document without validating their appropriate usage context—just because a key is listed doesn't mean it's authorized for all purposes. Implement defense-in-depth by verifying both document signatures and individual interaction proofs rather than trusting document contents without validation.

Caveat

Despite standardization efforts, DID Documents face significant practical limitations in current implementations. Interoperability challenges persist across different DID methods, with inconsistent implementation of optional features creating potential compatibility issues. Document size constraints in some methods limit the practical complexity of identity representations, particularly for entities requiring numerous verification methods or services. Resolution infrastructure remains relatively centralized for many methods, creating potential availability concerns. Most critically, the machine-readable nature of DID Documents creates significant usability challenges for human interpretation, requiring sophisticated interfaces to translate cryptographic structures into understandable representations that typical users can meaningfully consent to—a gap that current implementations have not fully bridged.

Blockchain & Cryptocurrency Glossary

DID Document - Related Articles