Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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. 

Motivations

This specification is intended to improves the way resources are stored and retrieved through the use of DID URLs, in the following ways:

  1. Highly available and easily retrievable
    1. Resources MUST be identified by a DID URL which allows them to be retrieved easily from a distributed ledger using existing DID Resolvers.
    2. Using a Verifiable Data Registry to store and index resources removes the problem identified by centralized systems creating single points of failure, which is a common problem in the way schemas, trust registries and revocation statuses are often stored.
  2. Controllable and self-attestable
    1. Resources MUST be tied to DID Documents and control over resources SHOULD be exerted via the same verification method keys as those written into an associated DID Document.
    2. This allows persons to authenticate with a DID Document to update or prove control of a resource, which addresses the problem of tamper-proofing identified around centralized cloud providers (which resources are currently commonly stored on).
  3. Built to be consumed by client applications
    1. Resources MUST specify a name, and resource type and compile into a media type, which provides specific information to any client application about what data format and syntax the data are expected to be retrieved in.
    2. This allows client applications to apply business rules to what types of resources are expected, and which should be accepted, making resources far easier to be consumed by third-party software. This differs from existing Hyperledger Indy resources, which require the client applications to be familiar with Indy in order to process and consume Indy resources.
  4. Indexable
    1. Resources SHOULD be versioned with unique identifiers, allowing previous versions to be archived within a collection, and retrieved through querying a unique ID or a version time.
    2. This mitigates the problem identified of link rot when using centralized storage systems since each version is archived immutably.

Verifiable Data Registry (VDR) and DID Method Requirements

...

Resource Parameters

The following list of Resource Parameters defines a common and detailed set of fields and parameters which an on-ledger resource SHOULD be which specific parameters a resource MUST contain to conform with this specification, and which parameters are OPTIONAL.

Resource ParameterRequirementDescription
"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: did:example:46e2af9a-2ea0-4815-999d-730a6778227c/resources/0f964a80-5d18-4867-83e3-b47f5a756f02, or, https://gateway.ipfs.io/ipfs/bafybeihetj2ng3d74k7t754atv2s5dk76pcqtvxls6dntef3xa6rax25xe


"resourceCollectionId"

NO
OPTIONAL

A string that conforms to a method specific unique identifier format.

For example: 46e2af9a-2ea0-4815-999d-730a6778227c

"resourceId"
NO
OPTIONAL

A string that conforms to a method specific unique identifier format.

For example: 0f964a80-5d18-4867-83e3-b47f5a756f02

"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: degreeLaw

"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: JSONSchema2020

"resourceVersionId"
NO
OPTIONAL

A string that uniquely identifies the version of the resource provided by the resource creator as a tag.

For example: 1.3.1

"mediaType"YES

A string that identifies the IANA-registered Media Type for a resource.

For example: application/json

"created"YES

A JSON String serialized as an XML Datetime normalized to UTC 00:00:00 and without sub-second decimal precision.

For example: 2020-12-20T19:17:47Z

"checksum"
NO
OPTIONAL

A string that provides a checksum (e.g. SHA256, MD5) for the resource to facilitate data integrity.

For example: 7b2022636f6e74656e74223a202274657374206461746122207d0ae3b0c44298

"previousVersionId"
NO
OPTIONAL The value of the property MUST be anstring.
//
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: 67618cfa-7a1d-4be3-b9b2-3a9ea52af305

"nextVersionId"
NOnull

DID Resolver 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 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.0This specification adds no additional requirements to a conforming DID document.

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:

OPTIONAL

 The value of the property MUST be anstring. The value must be 'null' if there is no next version. 

For example: null

Linked Resource Metadata

The Resource Parameters for a resource SHOULD be referenced within an associated DID Document didDocumentMetadata property, for example:

Code Block
languagejs
firstline1
titleLinked 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
    }
  ]
}


DID Resolver Requirements

  1. If a DID URL includes any of the 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. 
    1. If the DID resolver is unable to return the identified resource, the resolver MUST return an error (see Error Messages)
  2. If a DID URL includes the 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. 
    1. If the DID resolver is unable to return the identified resource in the requested media type, the resolver MUST return an error (see Error Messages)
  3. If a DID URL includes the resourceMetadata parameter with a value of false, a conforming DID resolver SHOULD ignore the parameter.
  4. If a DID URL includes a custom, implementation-specific path, specified by the associated DID method, a conforming DID resolver MUST return the digital resource identified by the DID URL from the VDR, provided such resource is available.
  5. 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.

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:

"versionIdversionIdversionAtXML Datetime&resourceType=JSONSchema2020&versionAt=2018-07-19T08:40:00ZresourceMetadataBoolean&versionAt=2018-07-19T08:40:00Z&resourceMetadata=true
ParameterTypeExample
"resourceId
ParameterTypeExample
"resourceId"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceId=0f964a80-5d18-4867-83e3-b47f5a756f02
"resourceName"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw
"resourceType"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020
"resourceVersionId"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceVersionId=1.3.1

"versionTime"

XML Datetimedid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&versionTime=2015-03-11T05:30:02Z
"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceId=0f964a80-5d18-4867-83e3-b47f5a756f02
"resourceName"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw
"resourceType"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020

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

"resourceVersionId"Stringdid:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceVersionId=1.3.1

"versionTime"

XML Datetime
ExampleExplanationError
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).
&resourceType=JSONSchema2020&versionTime=2015-03-11T05:30:02Z
"versionId"String
"notFound".
did:example:46e2af9a-2ea0-4815-999d-730a6778227c?
resourceName=degreeLaw&resourceType=JSONSchema2020&versionTime=2018-07-19T08:40:00ZThe identified resource does not exist at the versionTime.
versionId=0f964a80-5d18-4867-83e3-b47f5a756f02
"versionAt"XML Datetime
"notFound".
did:example:46e2af9a-2ea0-4815-999d-730a6778227c?resourceName=degreeLaw&resourceType=JSONSchema2020&
versionId=2.1.4

The identified version does not exist.

"notFound".
    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.

Linked Resource Metadata

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

...

languagejs
firstline1
titleLinked Resource Metadata

...

versionAt=2018-07-19T08:40:00Z
"linkedResource"Booleandid: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&versionAt=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.

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

ExampleExplanationError
did:example:46e2af9a-2ea0-4815-999d-730a6778227c

...

?resourceName=degreeLawThere 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".
    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.
      1. How the VDR shall determine the default media type for the resource written to the VDR.
      2. How the VDR shall return the resource in response to a request from a conforming DID resolver.
      3. 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.0This 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.

...