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). They include cryptographic material, verification methods, and service endpoints needed for secure, verifiable interactions.

Core Components

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

Identifiers

Every DID Document contains:

• DID Subject: The unique DID described (the id property)
• DID Controller: Entity authorized to change the document
• Also Known As: Optional additional identifiers for the same subject

Verification Methods

Verification methods are cryptographic mechanisms proving control over a DID, typically including public keys for signature verification, authentication, and encryption. Each has a unique identifier for precise reference.

Verification Relationships

Verification relationships define how verification methods are used:

• Authentication (verify DID subject)
• Assertion (issue claims)
• Key Agreement (encrypted communications)
• Capability Invocation
• Capability Delegation

Services

Services define interaction methods beyond cryptographic verification, including ID, type, and service endpoint (network address).

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

Representations

DID Documents can be serialized as:

• JSON (lightweight)
• JSON-LD (with Linked Data capabilities)

How DID Documents Function

A DID Resolver takes a DID as input, interacts with the verifiable data registry (blockchain, distributed ledger), retrieves or constructs the DID Document, and returns it. This enables cryptographic verification without centralized authorities.

The DID controller can add or revoke verification methods, modify services, and transfer control through cryptographic proofs as defined by the DID method.

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

Related Concepts

Decentralized Identifiers (DIDs): The unique identifiers that DID Documents describe.

DID Methods: Implementations defining how DIDs and DID Documents are created, read, updated, and deleted.

DID Resolution: Retrieving a DID Document from a DID.

DID URL Dereferencing: Retrieving a resource from a DID URL.