...
This document is a Pre-Draft Deliverable of the ToIP Foundation Technical Stack Working Group.
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 addition of the resource
parameter to 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.
...
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 in bold will be defined in one or more terms wikis as part of completing this specificationare linked to their definitions in the W3C Decentralized Identifiers (DIDs) 1.0 specification.
Purpose
...
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).
Motivations
Resolution The process of resolving a DID and dereferencing of 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:
...
For a DID URL, the return of the DID document to the resolver commences the second step of dereferencing (the processing of which depends on the DID URL and the DID method).
However there is an exception to this normal 2-step process is when the DID itself identifies a digital resource that can be returned directly from the VDR of the associated DID method. There are numerous examples of when 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), a governance framework, or another digital asset.
In this case, the client MAY wish to use a DID URL to return request that a DID resolver return the identified digital resource in a single step as shown in Figure 3:
...
Note that in this case the DID document is not involved in retrieval of the resource. Rather if a resolver calls a VDR using a DID URL that includes a resource
parameter conformant with this specification, the VDR will retrieve the identified digital resource and return that resource to the resolver directly.
The Resource Parameter
TODO
Normative Requirements
TODO
DID Method Requirements
TODO
DID Specification Registries Entry
...
To enable this single-step 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=true
, then when a resolver calls the associated VDR using that DID URL, the VDR returns the identified digital resource, not the DID document.
IMPORTANT: The fact that a digital resource can be returned directly using a DID URL that includes the resource=true
parameter does not mean the DID does not have an associated DID document like any other DID. It simply means this DID document is not involved directly in the combined resolution/dereferencing step. If the DID alone is resolved (without the resource=true parameter), it should 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, then it identifies other instances of the identified digital resource available via other DIDs or URLs.
Syntax
The parameter name is resource
. The parameter type is a Boolean, so the valid values are true
and false
. The parameter value of true
is case-sensitive and must be spelled out exactly. No other renderings of true
, i.e. T
, TRUE
, 1
, -1
, and so forth — are equivalent.
Example
Following is an example DID URL based on the fictional did:example:
DID method that includes the resource
parameter:
did:example:21tDAKCERh95uGgKbJNHYp?resource=true
Normative Requirements
- If a DID URL includes the
resource
parameter with a value oftrue
, a conforming DID resolver MUST return the digital resource identified by the DID from the VDR specified by the associated DID method provided such resource is available. - If the DID resolver is unable to return the identified resource. the resolver MUST return the error "
Resource not found
". - If a DID URL includes the
resource
parameter with any value other thantrue
(for example,false
), a conforming DID resolver SHOULD ignore the parameter. - 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.
DID Method Requirements
A DID method specification conforming to this specification to include support for the resource
parameter:
- MUST define:
- How the associated VDR shall map the DID to the identified digital resource;
- 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.
- MUST define how this parameter will interact with the following additional DID parameters defined in section 3.2.1 of the DID Core Specification.
- versionId
- If the
versionId
parameter is included in the DID URL, the resolver MUST return the identified version of the identified digital resource. - If the identified version does not exist, the resolver MUST return the error: "
Version not found
".
- If the
- versionTime
- If the
versionTime
parameter is included in the DID URL, the resolver MUST return the identified version of the identified digital resource. - If the identified version does not exist, the resolver MUST return the error: "
Version not found
".
- If the
- versionId
Registration with the W3C DID Specification Registries
The resource
parameter defined by this specification is registered with the W3C DID Specification Registries 1.0 at the following URL:
https://www.w3.org/TR/did-spec-registries/#resource
Contributors
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:
- Drummond Reed, Evernym
Other contributors MUST also add their name and membership affiliation.
Acknowledgements
...
- Brent Zundel, Evernym
- Daniel Hardman, SICPA
- Stephen Curran, Cloud Compass Computing
Acknowledgements
The authors wish to thank the editors and contributors to the W3C Decentralized Identifiers (DIDs) 1.0 specification and in particular co-editor Amy Guy for her help.
Licensing
This is a publicly available specification published by the ToIP Foundation under the following licenses:
- Copyright: Creative Commons Attribution 4.0.
- Patent: Joint Development Foundation W3C Mode (based on the W3C Patent Policy).