#Understanding DID Documents

This document explains DID Documents, one of the foundational elements of the W3C Decentralized Identifier (DID) specification. For a broader understanding of DIDs, see our Decentralized Identifiers explanation.

#What are DID Documents?

DID Documents are machine-readable documents containing information associated with a Decentralized Identifier (DID). These documents provide the cryptographic material, verification methods, and service endpoints needed to use a DID for secure, verifiable interactions.

Think of a DID Document as a public profile card for an entity (person, organization, device, or digital object) identified by a DID. The document doesn't contain personal data about the entity, but rather the cryptographic keys and services needed to verify its identity and interact with it securely.

#Core Components

A DID Document contains several key components that enable verification and interaction:

#Identifiers

Every DID Document contains identifiers that establish its context:

• DID Subject: The unique identifier (DID) that the document describes, represented in the id property.
• DID Controller: The entity authorized to make changes to the document, which may or may not be the same as the DID subject.
• Also Known As: Optional additional identifiers that refer to the same DID subject, creating connections between different identity systems.

#Verification Methods

Verification methods are cryptographic mechanisms that allow a DID controller to prove control over a DID. They typically include:

• Public Keys: Cryptographic keys used for signature verification, authentication, and encryption.
• Biometric Templates: Patterns derived from unique physical characteristics.
• Other Verification Material: Additional methods specific to particular use cases.

Each verification method has a unique identifier within the DID Document, enabling precise reference to specific cryptographic material.

#Verification Relationships

Verification relationships express how verification methods can be used for different purposes:

• Authentication: Methods that can be used to verify that an entity is the DID subject.
• Assertion: Methods used to issue verifiable claims on behalf of the DID subject.
• Key Agreement: Methods used for establishing encrypted communication channels.
• Capability Invocation: Methods that invoke capabilities on behalf of the DID subject.
• Capability Delegation: Methods that delegate capabilities to others.

#Services

Services define how to interact with the DID subject beyond cryptographic verification. Each service entry includes:

• ID: A unique identifier for the service within the DID Document.
• Type: The type of service being offered.
• Service Endpoint: The network address where the service can be accessed.

Services might include data storage endpoints, messaging services, verification credential issuers, or any other means of interacting with the DID subject.

#DID Document Structure

DID Documents follow a structured data model with predefined properties. They can be serialized in different formats, with JSON and JSON-LD being the most common.

#Basic Structure

Here's a simplified overview of the DID Document structure:

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "controller": "did:example:123456789abcdefghi",
  "verificationMethod": [...],
  "authentication": [...],
  "assertionMethod": [...],
  "keyAgreement": [...],
  "capabilityInvocation": [...],
  "capabilityDelegation": [...],
  "service": [...]
}

The @context property provides semantic context for the terms used in the document, enabling proper interpretation across different systems.

#Representations

DID Documents can be serialized in different formats (representations):

• JSON: A lightweight, human-readable format.
• JSON-LD: Extends JSON with Linked Data capabilities for enhanced semantic interoperability.

Other formats are possible as long as they can express the complete data model.

#How DID Documents Function

A DID Document serves as a bridge between an identifier (the DID) and the mechanisms needed to use that identifier for secure interactions.

#Resolution Process

When someone wants to interact with a DID subject, they first need to resolve the DID to its associated DID Document:

1. A DID Resolver takes a DID as input
2. The resolver interacts with the appropriate verifiable data registry (blockchain, distributed ledger, etc.)
3. The resolver retrieves or constructs the DID Document
4. The document is returned to the requester

This process allows a DID to be used for cryptographic verification without requiring a centralized authority.

#Control and Updates

The DID controller can perform operations on the DID Document, such as:

• Adding new verification methods
• Revoking compromised keys
• Adding or removing services
• Transferring control to a new controller

These operations are defined by the specific DID method being used and are typically secured through cryptographic proofs.

#Why DID Documents Matter

DID Documents provide several key benefits for decentralized identity systems:

#Self-Sovereign Control

By separating the cryptographic material from centralized authorities, DID Documents enable individuals and organizations to control their own digital identifiers. The controller can update verification methods and services without depending on external parties.

#Cryptographic Trust

DID Documents establish a foundation for cryptographically verifiable digital relationships. Rather than relying on trusted intermediaries, parties can verify each other's identities and claims directly through the cryptographic material in DID Documents.

#Service Discovery

Through service endpoints, DID Documents provide a standardized way to discover how to interact with a DID subject. This creates an interoperable ecosystem of identity-linked services.

#Privacy by Design

DID Documents are designed with privacy as a core principle. They contain no personal data, only the cryptographic and service information needed for secure interaction. This separation enables selective disclosure of personal information through separate, encrypted channels.

#Example DID Document

Here's a complete example of a DID Document:

{
    "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/ed25519-2020/v1"],
    "id": "did:example:123456789abcdefghi",
    "controller": "did:example:123456789abcdefghi",
    "verificationMethod": [
        {
            "id": "did:example:123456789abcdefghi#keys-1",
            "type": "Ed25519VerificationKey2020",
            "controller": "did:example:123456789abcdefghi",
            "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
        }
    ],
    "authentication": ["did:example:123456789abcdefghi#keys-1"],
    "assertionMethod": ["did:example:123456789abcdefghi#keys-1"],
    "service": [
        {
            "id": "did:example:123456789abcdefghi#linked-domain",
            "type": "LinkedDomains",
            "serviceEndpoint": "https://example.com"
        }
    ]
}

In this example:

• The document identifies a subject with the DID did:example:123456789abcdefghi
• The subject is also the controller of the document
• It contains one verification method (an Ed25519 public key)
• This key can be used for both authentication and making assertions
• It offers one service endpoint for linked domains

#Related Concepts

DID Documents work as part of a broader decentralized identity ecosystem:

• Decentralized Identifiers (DIDs): The globally unique identifiers that DID Documents describe.
• DID Methods: The specific implementations that define how DIDs and DID Documents are created, read, updated, and deleted on a particular system.
• DID Resolution: The process of retrieving a DID Document from a DID.
• DID URL Dereferencing: The process of retrieving a resource from a DID URL.
• Verifiable Credentials: Claims about a DID subject that can be cryptographically verified using the verification methods in the DID Document.
• Verifiable Data Registries: The systems where DIDs are recorded and from which DID Documents are retrieved.

#Summary

DID Documents are foundational building blocks of decentralized identity systems. They provide the cryptographic material and service information needed to use DIDs for secure, verifiable interactions while maintaining privacy and self-sovereign control.

By separating identity verification from centralized authorities, DID Documents enable a more resilient, user-controlled approach to digital identity that aligns with the principles of privacy by design and decentralized control.