Document Status

This document is a Draft Deliverable of 'TBC'.

The current version is Working Draft 01.

Introduction

This is a specification for an extension to the W3C Decentralized Identifiers (DIDs) 1.0 specification to support the use of on-ledger resources, as listed in the W3C DID Specification Registries 1.0. This specification is also intended to act as a Version 2.0 iteration of the DID URL Resource Parameter Specification.

Terminology

In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL", when appearing in ALL CAPITALS, are to be interpreted as described in RFC 2119.

All other terms are linked to their definitions in the W3C Decentralized Identifiers (DIDs) 1.0 specification.

Purpose

The purpose of this specification is to specify how:

• Resources SHOULD be written to a Verifiable Data Registry
• Resources SHOULD be linked to DID Documents, whose verification method keys are able to authenticate/update/manage the resource
• Resources SHOULD be directly identifiable and retrievable via a DID URL, using DID URL Dereferencing in line with the W3C Decentralized Identifiers (DIDs) 1.0 specification.
• Permutations of DID URLs SHOULD fetch different information about a resource or collection of resources
• Metadata describing the resource MAY be included as additional DID Document Metadata
  

Context

This specification builds on two existing concepts for processing a DID URL:

DID Resolution

DID Resolution is the process of resolving the plain DID (defined by the ABNF from section 3.1 of the DID spec) to a DID document.

This flow is shown by figure 1, below:

Figure 1: The normal DID resolution process

DID URL Dereferencing

DID URL Dereferencingis the process of resolving a DID to a DID document in order to determine how to dereference the remainder of the DID URL (path, query, fragment as defined by the ABNF in section 3.2 of the DID 1.0 specification.)

The path, query or fragment within the DID URL provides a DID Resolver additional specific information regarding the exact object within the DID Document that should be returned.

Normal dereferencing can be conceived in two steps:

1. A DID is resolved to a DID Document;
2. A resource within the DID Document is identified, based on the portion of the DID URL that follows the DID (path, query, fragment as defined by the ABNF in section 3.2 of the DID 1.0 specification.).
   

An example is processing a DID fragment to return a specific public key from the DID Document. Or alternatively, processing a DID query to return a specific service endpoint, specified in the service section of the DID Document.

This flow is shown by figure 2, below:

Figure 2: The normal DID URL Dereferencing process

(Note: The specifics of how dereferencing operates depends on the DID URL and the DID method.)

Motivations

The aim of this specification is to create a more resilient, tamper-resistant, highly available and standardized way of storing, referencing and retrieving resources (such as data schemas, interface definitions, governance or policy definitions), using DID URLs. 

On-ledger Resources identifiable via DID URLs

Central to this specification is the idea of a DID URL dereferencing directly to a resource, rather than first dereferencing to a DID Document. 

This is an exception to the normal 2-step resolution/dereferencing process, enabling the DID itself to directly identify a digital resource that can be returned directly by the VDR of the associated DID method. This behavior may be desirable:

• When the DID serves as a persistent identifier of a machine-readable digital resource that the client wishes to consume directly, such as a data schema, interface definition, or policy definition.
• When the DID serves as a persistent identifier of a human-readable document that needs a long-lived, cryptographically verifiable identifier such as a legal document (e.g., title, deed, will, regulatory filing), a governance framework, or a non-fungible token (NFT) or any other type of digital asset.

This flow is shown in figure 3, below:

Figure 3: The relationship of DIDs, DID URLs, DID documents, and Resources

In this case, the client MAY wish to use a DID URL to request that a DID resolver return the identified digital resource in a single step.

Three important notes about this process:

1. The DID document is not retrieved by the resolver as part of the dereferencing process. Rather the resolver makes a call to the VDR with the DID URL including a resource parameter conformant with this specification. The VDR then follows the specification of the associated DID method to retrieve the identified digital resource and return that resource to the resolver directly.
2. The resource is still associated with a DID Document. A DID URL that includes the resource parameter does still have an associated DID document like any other DID. However if the DID URL includes the resource parameter, the associated DID document is not involved in the combined resolution/dereferencing step to fetch the resource specified. If the DID alone is resolved (without the resource parameter), it will still return the associated DID document.
   1. 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.
   2. If the DID document contains one or more verification methods, the same verification methods may be used for authenticating/versioning/updating the identified digital resource and/or the DID document.
3. The DID Document refers to the associated resource via linked resource metadata. Through associating the resource with a DID Document, the DID Document may generate associated metadata about the resource, defined further below. 

Query Syntax for Resource DID URLs

To enable this combined resolution/dereferencing behavior, this specification defines multiple DID URL parameters to fetch resource. If a DID method specification supports these parameters, and if a DID URL using that method includes the parameter with a valid value, then when a resolver calls the associated VDR using that DID URL, the VDR returns the identified digital resource, not the DID document.

IMPORTANT: DID URL queries should be fully qualified so that they uniquely identify a single resource, or single resource version. 

Common and standardized resource parameters:

Error messages

There MAY be instances where the resolver has not been provided enough specific information to process the request and fetch a single resource. 

In these cases, the error messages should follow the Error section in the DID Resolution specification here. 

Verifiable Data Registry (VDR) and DID Method Requirements

A Verifiable Data Registry (VDR) and DID Method conforming to this specification to include support for resources identifiable via DID URLs:

1. MUST define:
   1. A method to write a resource to the VDR resource which is mapped to an associated DID Document

   2. A method to map the individual fields of the resource metadata to the resource parameters listed above.

   3. A method to reference resources within the associated DID Document: 

      1. MAY 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. This approach MAY be used when there is ONLY one resource associated with a DID and DID Document.

      2. MAY include references to the associated on-ledger resources within the didDocumentMetadata property, for example:

         Linked Resource Metadata

         "didDocumentMetadata": {
           "created": "2022-07-19T08:29:07Z",
           "versionId": "57543FA1D9C56033BABBFA3A438E0A149E01BBB89E6D666ACE1243455AA6F2BC",
           "linkedResourceMetadata": [
             {
               "resourceURI": "did:cheqd:mainnet:46e2af9a-2ea0-4815-999d-730a6778227c/resources/0f964a80-5d18-4867-83e3-b47f5a756f02",
               "resourceCollectionId": "46e2af9a-2ea0-4815-999d-730a6778227c",
               "resourceId": "0f964a80-5d18-4867-83e3-b47f5a756f02",
               "resourceName": "DegreeLaw",
               "resourceType": "CL-Schema",
               "mediaType": "application/json",
               "created": "2022-07-19T08:40:00Z",
               "checksum": "7b2022636f6e74656e74223a202274657374206461746122207d0ae3b0c44298",
               "previousVersionId": null, // null if no previous version, otherwise, resourceId of previous version
               "nextVersionId": null, // null if no new version, otherwise, resourceId of new version
             }
           ]
         }

   4. How the VDR shall determine the default media type for the resource written to the VDR.
   5. How the VDR shall return the resource in response to a request from a conforming DID resolver.
   6. Important: If the DID alone is resolved without a 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. To enable this combined resolution/dereferencing behavior, this specification defines multiple new DID URL parameters for retrieving resources. If a DID method specification supports this specification, and if a DID URL using that method includes a parameter with a valid value, then when a resolver calls the associated VDR using that DID URL, the VDR returns the identified digital resource, or metadata associated with the resource.

Resource fields