DID URL

A DID URL is a Uniform Resource Locator that extends a base Decentralized Identifier (DID) to point to a particular component within its associated DID document. It follows the syntax defined in the W3C DID specification, structured as did:method:identifier/path?query#fragment. The core DID (did:method:identifier) resolves to the entire document, while the optional path, query, and fragment components allow for precise referencing of embedded resources like cryptographic public keys, service endpoints, or specific JSON properties.

The primary function of a DID URL is to enable granular and verifiable references. For instance, in a Verifiable Credential, the proof section doesn't just state which DID created it; it uses a DID URL like did:example:123456789abcdefghi#key-1 to specify the exact public key (#key-1 fragment) within the issuer's DID document that should be used for signature verification. This eliminates ambiguity and ensures cryptographic proofs are bound to a specific key, even if the DID controller rotates or manages multiple keys.

Beyond key references, the path component can be used to address nested resources or services. A DID URL like did:web:example.com:user:alice/service/agent could point directly to a messaging endpoint described in the DID document. The query component allows for parameterized requests, such as requesting a document in a specific format. This structure makes DID URLs a powerful tool for decentralized interactions, enabling services, applications, and other DIDs to interact with precise, machine-readable addresses without relying on a central registry.

From an implementation perspective, developers must ensure their DID resolver can properly parse and dereference DID URLs. This involves first resolving the base DID to its document, then navigating the JSON structure using the URL's components. Proper handling is critical for security, as incorrectly resolving a DID URL could lead to using the wrong key for verification. The standardization of this syntax is a key enabler for interoperability across different DID methods and decentralized identity ecosystems.

A DID URL (Decentralized Identifier URL) is a URI string that extends a base DID (Decentralized Identifier) with optional path, query, and fragment components to identify a specific resource within a DID document or enable a specific interaction with it. Its formal syntax is defined by the W3C Decentralized Identifiers (DIDs) v1.0 specification, which builds upon the foundational IETF RFC 3986 URI standard. This design ensures DID URLs are both machine-readable and interoperable with existing web infrastructure, while being resolvable to cryptographically verifiable data.

The term's origin lies in the need to reference not just the identity subject (the DID itself) but also specific verification methods (like public keys), service endpoints, or portions of the DID document's JSON structure. For example, the fragment component (the part after a #) is commonly used to point to a specific key: did:example:123456789abcdefghi#key-1. This allows for precise, granular referencing essential for verifiable credentials and selective disclosure, where you might need to prove control over one key without revealing others.

The adoption of the URI scheme was a deliberate architectural choice to leverage decades of web standards. It provides a well-understood mechanism for decomposition and resolution. The DID method (the segment after did:, like ethr or key) defines the specific rules for how the DID and its appended URL components are resolved to a DID document on its respective blockchain or decentralized network. This makes the DID URL a universal locator for decentralized resources, bridging the gap between classic web addresses and trust-minimized, cryptographic identity.

A DID URL extends a core Decentralized Identifier (DID) by appending path components, query strings, or fragments, following the syntax defined in the W3C DID specification. The base DID (e.g., did:example:123456) uniquely identifies a subject on a verifiable data registry, while the appended components create a pointer to a specific resource within that DID's DID document. This mechanism allows for precise addressing, similar to how a traditional URL points to a specific page or file on a website, but within a decentralized identity system.

The structure of a DID URL is did:method:identifier/path?query#fragment. The path component typically references a service endpoint listed in the DID document, such as a messaging inbox or a credential repository. The query string can be used to request specific representations or parameters, and the fragment (#) uniquely identifies a specific key or section within the DID document itself, like did:example:123456#key-1. This granular addressing is crucial for cryptographic operations, where a verifier must reference the exact public key used for signing.

Resolving a DID URL is a two-step process handled by a DID resolver. First, the resolver fetches the DID document by processing the DID method (e.g., did:ethr:, did:web:) to query the corresponding blockchain or decentralized network. Once the DID document is retrieved, the resolver parses the appended URL components to locate the specific resource—whether it's a service endpoint URL, a public key description, or another linked resource. This resolution process enables trusted, machine-readable interactions without relying on a central directory.

Practical applications of DID URLs are extensive. They are used to dereference a specific verification key for checking a digital signature, to access a Verifiable Credential stored at a remote service endpoint, or to initiate a secure communication channel via a service listed in the DID document. For example, a DID URL like did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK directly identifies a public key for encryption, enabling secure, decentralized data exchange.

A DID URL is a Uniform Resource Locator that extends a standard Decentralized Identifier (DID) with optional path, query, and fragment components, allowing one to address specific resources within a DID document or associated services. The resolution process, defined by the W3C DID Core specification, is the mechanism by which a DID resolver takes a DID URL as input and returns a DID document or a resource described therein. This is a foundational operation for all decentralized identity systems, enabling verifiable credentials, authentication, and secure service endpoints.

The resolution process typically involves several key steps. First, the resolver parses the DID URL to extract the DID method (e.g., did:ethr, did:web) and the method-specific identifier. It then interacts with the corresponding DID method's underlying system—which could be a blockchain, a distributed ledger, a peer-to-peer network, or a hosted file—to fetch the current DID document. If the URL contains a path or query, the resolver processes these components to locate a specific service endpoint, key, or other resource described in the document's service or verificationMethod sections.

A critical distinction is between DID Resolution and DID URL Dereferencing. Resolution strictly returns the DID document itself. Dereferencing goes further, interpreting the optional components of the DID URL to return the specific resource pointed to, such as a public key for verification (#key-1) or a service endpoint for messaging. The process must also handle DID document metadata, including versioning information, proof of integrity, and deactivation status, ensuring the resolver returns a complete DID resolution result that includes both the document and this metadata.

In practice, resolution can be performed by universal resolvers that support multiple DID methods or by method-specific resolvers. For example, resolving did:ethr:0xb9c5714089478a327f09197987f16f9e5d936e8a involves querying an Ethereum smart contract, while did:web:example.com:user:alice might fetch a JSON document from a well-known HTTPS endpoint. The security of the entire ecosystem depends on the integrity of this process, as the resolved document forms the root of trust for all subsequent cryptographic verifications and interactions with the identity holder.