...

The current version is Working Draft 0102.

Introduction

This is a specification for an extension to the W3C Decentralized Identifiers (DIDs) 1.0 specification to support the resource parameter as listed in the W3C DID Specification Registries 1.0. It specifies the syntax and normative behavior for usage of the parameter and the requirements for DID methods that support the parameter.

...

The purpose of this specification is to specify how a DID URL may include a parameter that instructs a DID resolver to request the associated verifiable data registry (VDR) to directly return a digital resource identified by a decentralized identifier (DID). This parameter is only available for DID URLs whose DID method supports the parameter. The parameter also supports requesting the resource in a particular media type. 

Motivations

The process of resolving a DID and dereferencing a DID URL (meaning a DID that includes an additional path, query, and/or fragment component as defined by the ABNF in section 3.2 of the DID 1.0 specification) is shown in figure 1 from section 7.2 of the spec:

...

To enable this combined resolution/dereferencing behavior, this specification defines a DID URL parameter named resource. If a DID method specification supports this parameter, and if a DID URL using that method includes the parameter value resource=truewith a valid value (either true or a valid media type name), then when a resolver calls the associated VDR using that DID URL, the VDR returns the identified digital resource, not the DID document.

IMPORTANT: A DID URL that includes the resource=true parameter  parameter still has an associated DID document like any other DID. However this DID document is not involved in the combined resolution/dereferencing step. If the DID alone is resolved (without the resource=true parameter parameter), it will still return the associated DID document. There is nothing special about this DID document. It still describes and controls interactions with the identified digital resource just like any other DID document. For example:

• If the DID document contains only an id property (whose value must be the DID) and no verification methods, then the DID document cannot be updated and the identified digital resource is a static resource that cannot be versioned.
• If the DID document contains one or more verification methods, then the DID controller has a method for versioning the identified digital resource and/or the DID document itself.

If the DID document contains one or more alsoKnownAs property values, those values still identify other instances of the identified digital resource available via other URIs, URLs, or DIDs. (See also the recommendation below to include an alsoKnownAs property whose value is a hashlink to the identified digital resource.)

Syntax

The parameter name MUST be resource. The parameter type value MUST be a Boolean for which the valid values are true and falseone of the following:

1. A Boolean value of true. The parameter value of true MUST be case-sensitive and MUST be spelled out exactly. No other renderings of true, i.e.  T, TRUE, 1, -1, and so forth — are equivalent.
2. A valid media type name. If the VDR supports the storage of the resource in multiple media types, this option enables the client to request return of a specific media type.

Example

Following is an example DID URL are examples of DID URLs based on the fictional did:example: DID method that includes include the resource parameter:

did:example:21tDAKCERh95uGgKbJNHYp?resource=true

did:example:21tDAKCERh95uGgKbJNHYp?resource=json

did:example:21tDAKCERh95uGgKbJNHYp?resource=ld+json

did:example:21tDAKCERh95uGgKbJNHYp?resource=cbor

DID Resolver and Verifiable Data Registry (VDR) Requirements

1. If a DID URL includes the resource parameter with a value of true, a conforming DID resolver MUST return the default media type of the digital resource identified by the DID from the VDR specified by the associated DID method provided such resource is available. 
   1. If the DID resolver is unable to return the identified resource, the resolver MUST return the error "Resource not found".
2. If a DID URL includes the resource parameter with a value of a valid media type name, a conforming DID resolver MUST return the requested media type of the digital resource identified by the DID from the VDR specified by the associated DID method provided such resource is available. 
   1. If the DID resolver is unable to return the identified resource in the requested media type, the resolver MUST return the error "Resource not found".
3. If a DID URL includes the resource parameter with any value other than true (for example, false)a value of false, a conforming DID resolver SHOULD ignore the parameter.
4. If the DID alone is resolved without the resource parameter, it MUST return the authoritative DID document as defined in W3C Decentralized Identifiers (DIDs) 1.0. This specification adds no additional requirements to a conforming DID document.

...

1. MUST define:
   1. How the associated VDR shall map the DID to the identified digital resource ;in the identified media type.
   2. If the resource parameter has a value of true, how the VDR shall determine the default media type.
   3. How the VDR shall return the resource in response to a request from a conforming DID resolver.
   MAY define additional DID document properties to enable dereferencing to the target digital resource, however this is discouraged vs. the alternative of storing such dereferencing metadata in the VDR itself
   1. .
2. MUST define how this parameter will interact with the following additional DID parameters defined in section 3.2.1 of the DID Core Specification.
   
   1. versionId
      
      1. If the versionId parameter is included in the DID URL, the resolver MUST return the identified version of the identified digital resource.
      2. If the identified version does not exist, the resolver MUST return the error: "Version not found".
   2. versionTime
      
      1. If the versionTime parameter is included in the DID URL, the resolver MUST return the identified version of the identified digital resource.
      2. If the identified version does not exist, the resolver MUST return the error: "Version not found".
3. SHOULD include in the associated DID document an alsoKnownAs property containing at least one value that is a hashlink to the identified digital resource. This provides additional cryptographic verification of the binding between the DID and the identified digital resource.
4. SHOULD NOT define any additional DID document properties to enable dereferencing to the target digital resource. This is an anti-pattern. The best practice is to store the mapping between the DID and the identified digital resource within the VDR itself. This way the VDR can evolve its internal storage mechanisms without requiring DID controllers to make any changes to their DID documents.

Registration with the W3C DID Specification Registries

...