DID URL Dereferencing

In the world of decentralized identifiers, dereferencing is a fundamental process that enables resources to be retrieved using DIDs. This document explains the core concepts of DID URL dereferencing, how it differs from DID resolution, and why it matters within the Vidos ecosystem.

What is DID URL Dereferencing?

DID URL dereferencing is the process of retrieving a resource identified by a DID URL. While this might sound similar to DID resolution, there’s an important distinction to understand.

DID Resolution vs. DID URL Dereferencing

These two processes serve different but complementary purposes in the DID ecosystem:

Process	Purpose	Input	Output
DID Resolution	Obtains a DID document for a given DID	A DID (did:example:123)	A complete DID document
DID URL Dereferencing	Retrieves a specific resource identified by a DID URL	A DID URL (did:example:123/path?query#fragment)	A specific resource (document fragment, verification method, service endpoint, or external resource)

Think of the relationship like this:

• DID resolution answers: “What is the complete DID document for this identifier?”
• DID URL dereferencing answers: “What specific resource is identified by this DID URL?”

How DID URL Dereferencing Works

The dereferencing process typically follows these steps:

1. Parse the DID URL: The system extracts the DID portion and any additional components (path, query parameters, fragment).

2. Resolve the DID: The base DID is resolved to obtain the corresponding DID document.

3. Identify the Target Resource: Based on the additional components (path, query, fragment), the system identifies which specific resource is being requested.

4. Return the Resource: The identified resource is returned to the requester.

Components that Affect Dereferencing

A DID URL contains several components that determine what resource will be returned:

• DID: The base identifier (did:example:123)
• Path: Points to a specific resource (/service/agent)
• Query Parameters: Provide additional instructions (?versionTime=2023-06-01)
• Fragment: Identifies a specific part of the resource (#key-1)

Common Use Cases for DID URL Dereferencing

DID URL dereferencing enables several important capabilities:

1. Verification Method Access: Retrieving a specific cryptographic key from a DID document (did:example:123#key-1).

2. Service Endpoint Retrieval: Accessing a service endpoint associated with a DID (did:example:123?service=messaging).

3. External Resource Access: Obtaining resources hosted by the DID controller (did:example:123/resume.pdf).

4. Historical Version Access: Retrieving a specific version of a DID document (did:example:123?versionTime=2023-01-01).

5. Linked Resource Retrieval: Obtaining resources linked to a DID through its verifiable data registry.

Dereferencing Outcomes

When dereferencing a DID URL, one of three main outcomes can occur:

1. Success with Resource: The dereferencing succeeds and returns the requested resource.

2. Success with Redirection: The dereferencing succeeds but indicates the resource is located elsewhere.

3. Failure: The dereferencing fails due to various issues (invalid DID URL, resource not found, lack of access permissions).

Metadata in DID URL Dereferencing

Metadata plays a crucial role in the dereferencing process:

• Dereferencing Options: Input metadata that affects how dereferencing occurs (e.g., specifying preferred content type).

• Dereferencing Metadata: Output metadata about the dereferencing process (e.g., content type of the returned resource).

• Content Metadata: Information about the retrieved resource (e.g., when it was created/updated).

Processing DID URL Parameters

DID URL parameters influence how dereferencing happens:

• service: Identifies a service endpoint in the DID document
• relativeRef: Specifies a resource relative to a service endpoint
• versionId: Requests a specific version of a DID document
• versionTime: Requests the DID document as it existed at a specific time
• hl: Provides integrity protection through resource hashing

Error Handling in Dereferencing

When dereferencing fails, the system returns specific error codes to help understand what went wrong:

• invalidDidUrl: The DID URL syntax is invalid
• notFound: The requested resource doesn’t exist
• contentTypeNotSupported: The requested content type isn’t available

Relationship to the Vidos Universal Resolver

The Vidos Universal Resolver implements DID URL dereferencing according to the W3C DID Core specification. It provides a standardized way to obtain resources across different DID methods, ensuring consistency and interoperability throughout the Vidos ecosystem.

Security and Privacy Considerations

When using DID URL dereferencing:

• Consider that dereferencing might reveal information about which resources are being accessed
• Be aware that some resources might require authentication or authorization
• Verify the integrity of retrieved resources when needed, especially for critical operations
• Consider caching implications, particularly for frequently accessed resources

Key Takeaways

• DID resolution retrieves complete DID documents; DID URL dereferencing retrieves specific resources
• DID URL dereferencing is essential for interacting with specific parts of a DID or resources it controls
• The process involves parsing the DID URL, resolving the DID, and retrieving the specified resource
• Parameters and fragments in the DID URL precisely identify the requested resource
• Proper error handling and metadata processing are crucial for reliable dereferencing

By understanding DID URL dereferencing, you gain insight into how Vidos enables precise, flexible interactions with decentralized identifiers and the resources they control.