This document is a Draft Deliverable of the Utility Foundry Working Group.
The current version is Working Draft 01.
This is a specification for an extension to the W3C Decentralized Identifiers (DIDs) 1.0 specification to support the identification of Resources linked to DIDs, as listed in the W3C DID Specification Registries 1.0, using DID URLs. This specification is intended to supersede the DID URL Resource Parameter Specification.
In this document, the keywords "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.
The aim of this specification is to define how DID URLs SHOULD act as persistent identifiers for referencing and retrieving Resources (such as data schemas, interface definitions, governance documents, or policy definitions). Through using DID URLs which remain conformant with W3C Decentralized Identifiers (DIDs) 1.0 specification, existing DID Resolvers will be able to dereference these DID URLs to retrieve the identified resource using the DID URl query syntax in this specification.
This specification builds on two existing concepts for processing a DID URL:
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 in figure 1, below:
Figure 1: The normal DID resolution process
DID URL Dereferencing is 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:
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. (Note: the process for how a DID Document is dereferenced is left to each DID Method implementation.)
This flow is shown in figure 2, below:
Figure 2: The normal DID URL Dereferencing process
Although the DID Core specification defines an interoperable standard for DID Documents and associated core properties, it currently does not have a standardised way to specify properties of Resources and how to fetch them. A Resource is defined as any file or digital asset that is linked to a DID (such as schemas, credential definitions, trusted issuer lists, logos, image assets for credentials etc). Specifying
This specification is intended to improve the way Digital Resources are stored and retrieved through the use of DID URLs, in the following ways:
DID URLs SHOULD be able to dereference 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 behaviour may be desirable:
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:
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.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. 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.A Verifiable Data Registry (VDR) and DID Method conforming to this specification to include support for resources
identifiable via DID URLs MUST define:
A Verifiable Data Registry (VDR) and DID Method conforming to this specification to include support for resources
identifiable via DID URLs SHOULD define:
A Verifiable Data Registry (VDR) and DID Method conforming to this specification to include support for resources
identifiable via DID URLs MAY define:
The following list defines which specific parameters a resource MUST contain to conform with this specification, and which parameters are OPTIONAL.
Resource Parameter | Requirement | Description |
---|---|---|
"resourceUri" | YES | A string or a map that conforms to the rules of [RFC3986] for URIs which SHOULD directly lead to a location where the resource can be accessed from. For example: |
| OPTIONAL | A string that conforms to a method specific unique identifier format. For example: |
"resourceId" | OPTIONAL | A string that conforms to a method specific unique identifier format. For example: |
"resourceName" | YES | A string that uniquely names and identifies a resource. This property, along with the resourceType below, can be used to track version changes within a resource. For example: |
"resourceType" | YES | A string that identifies the type of resource. This property, along with the resourceName above, can be used to track version changes within a resource. Not to be confused with media type. (TBC to add to DID Spec Registries) For example: |
"resourceVersionId" | OPTIONAL | A string that uniquely identifies the version of the resource provided by the resource creator as a tag. For example: |
"mediaType" | YES | A string that identifies the IANA-registered Media Type for a resource. For example: |
"created" | YES | A JSON String serialized as an XML Datetime normalized to UTC 00:00:00 and without sub-second decimal precision. For example: |
"checksum" | OPTIONAL | A string that provides a checksum (e.g. SHA256, MD5) for the resource to facilitate data integrity. For example: |
"previousVersionId" | OPTIONAL | The value of the property MUST be an string. This is the previous version of a resource with the same resourceName and resourceType. The value must be 'null' if there is no previous version. For example: |
"nextVersionId" | OPTIONAL | The value of the property MUST be an string. The value must be 'null' if there is no next version. For example: |
The Resource Parameters for a resource SHOULD be referenced within an associated DID Document didDocumentMetadata
property, for example:
"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 } ] } |
resource
Query Syntax Parameters (below), a conforming DID resolver MUST return the digital resource identified by the DID URL from the VDR, provided such resource is available. resourceMetadata
parameter with a value of true
, a conforming DID resolver MUST return the requested associated metadata of the digital resource identified from the VDR, provided such resource is available. resourceMetadata
parameter with a value of false
, a conforming DID resolver SHOULD ignore the parameter.resource
parameter, it MUST return the authoritative DID document as defined in W3C Decentralized Identifiers (DIDs) 1.0.To enable combined resolution/dereferencing behavior, this specification defines multiple DID URL parameters to fetch resource
or associated metadata. 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 unless expressly specified.
Common and standardized resource
parameters:
Parameter | Type | Example |
---|---|---|
"resourceId" | String | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceId=0f964a80-5d18-4867-83e3-b47f5a756f02 |
"resourceName" | String | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw |
"resourceType" | String | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020 |
"resourceVersionId" | String | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceVersionId=1.3.1 |
| XML Datetime | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&versionTime=2015-03-11T05:30:02Z |
"versionId" | String | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?versionId=0f964a80-5d18-4867-83e3-b47f5a756f02 |
"versionTime" | XML Datetime | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&versionTime=2018-07-19T08:40:00Z |
"linkedResource" | Boolean | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?linkedResource=true // note that this would only be a valid query if there is ONLY ONE resource associated with the DID and DID Document. |
"resourceMetadata" | Boolean | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&versionTime=2018-07-19T08:40:00Z&resourceMetadata=true or, did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceMetadata=true // note that this would only be a valid query if there is ONLY ONE resource associated with the DID and DID Document. |
"latestResourceVersion " | Boolean | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&latestResourceVersion=true |
"allResourceVersions " | Boolean | did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&allResourceVersions=true |
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.
Example | Explanation | Error |
---|---|---|
did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw | There MAY be insufficient information for the VDR to process the request (for example, if there are multiple resource versions of the name degreeLaw, or different resource types of the name degreeLaw). | "notFound ". |
did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&versionTime=2018-07-19T08:40:00Z | The identified resource does not exist at the versionTime. | "notFound ". |
did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&versionId=2.1.4 | The identified version does not exist. | "notFound ". |
The Query Syntax for Resource DID URLs defined by this specification will be registered with the W3C DID Specification Registries 1.0 at the following URL:
https://www.w3.org/TR/did-spec-registries/#resource
To comply with the intellectual property rights protections in the charter of the ToIP Foundation (as required by all Joint Development Foundation projects hosted the Linux Foundation), all contributors to this Pre-Draft Deliverable MUST be current members of the ToIP Foundation. The following contributors each certify that they meet this requirement:
The authors wish to thank the editors and contributors to the W3C Decentralized Identifiers (DIDs) 1.0 specification.
This is a publicly available specification published by the ToIP Foundation under the following licenses: