Overview

Our objective in building DID-Linked Resources on cheqd is to improve the way resources are stored, referenced and retrieved for our partners and the broader SSI community, in line with the existing W3C DID Core standard.

Contents

Read the guides below to understand the context, rationale and design decisions involved in the DID-Linked Resource (DLR) implementation on cheqd.

Architecture for DID-Linked Resources

If you are interested in diving into the full architectural decisions for DID-Linked Resources, head to our ADR and the emerging W3C specification.

As a general architectural overview for DID-Linked Resources, see the diagram below:

Support for AnonCreds using DID-Linked Resources

One of the functions of DID-Linked Resources is enabling support for AnonCreds on cheqd, where previously these were tied into the Hyperledger Indy ecosystem. Take a look at our AnonCreds documentation here:

The /resource/search API allows users to search for specific entries of a Resource on the cheqd Network. For example, if there are multiple Resources associated with the same DID, the search functionality allows applications to make requests only to a specified Resource.

"DID-Linked Resources" are identified with a did:cheqd Decentralized Identifier with a Universally Unique Identifier (UUID) that acts as a permanently-accessible link to fetch the resources from the cheqd ledger. We refer to this as the "resource ID". Through the "resource ID" or a set of DID URL query parameters, applications are able to persistently access a digital resource on the cheqd network.

Get started

Alternatives

Below are a list of alternatives for creating cheqd DID-Linked Resources.

Partner SaaS support

cheqd DID-Linked Resources are supported in SaaS offerings from cheqd partners, making it possible to use did:cheqd DLRs across different platforms:

DID-Linked Resource Write Pricing

Read up on our identity write pricing for cheqd Mainnet below:

Using the /resource/create API, users are able to create custom DID-Linked Resources, including:

1. Schemas

2. Credential Definitions

Verifiable Credentials (VCs) often need to reference external data to provide structure, governance, or context. On the cheqd network, these external references can be anchored as DID-Linked Resources, enabling permanent, tamper-evident, and verifiable links within the credential itself.

This tutorial explains how to reference DID-Linked Resources in the body of a VC using fully qualified did:cheqd URLs. These references enhance trust, interoperability, and auditability of issued credentials.

Common Resources to Reference in a VC

The table details what types of DID-Linked Resources may commonly be included within the body of a Verifiable Credential:

Example: Event Ticket Credential with Schema & Logo References

Below is a Verifiable Credential issued for an event ticket. It references:

• A schema, published as a DID-Linked Resource

• A logo, hosted as a visual asset under the same issuer DID

Dereferencing the schema

The VC references a schema hosted as a DID-Linked Resource. Resolving this DID URL returns:

Understanding "Resources" in decentralised identity

In self-sovereign identity (SSI) ecosystems, “resources” are often required in tandem with W3C Verifiable Credentials, to provide supporting information or additional context to verifiers receiving Verifiable Presentations.

For example, common types of resources that might be required to issue and validate Verifiable Credentials are:

• Schemas;

• Status lists;

• Trust registries;

• Visual Representations of Verifiable Credentials;

• Documents; or

• Logos

Schemas

Schemas describe in a machine-readable format. Prominent examples of this include , , etc. You can think of them as a template for what is included in a Verifiable Credential.

Below is an example of a residential address with full URLs:

This might also take the form of evidence schemes, which describe additional information about the processes used to validate the information presented in a Verifiable Credential in common, machine-readable format.

Prominent examples of this include , , etc.

Status and Revocation Lists

Status lists allow recipients of a Verifiable Credential exchange to for validity. Prominent examples of this include the specification, , etc.

Trust registries

Trust registries enable recipients of a Verifiable Credential exchange to check that the Decentralized Identifier of the issuer is listed in a trusted registry. This provides a level of assurance in the authenticity of the issuer. Examples of Trust Registries include the , , etc.

Visual representations for Verifiable Credentials

Although Verifiable Credentials can be exchanged digitally, in practice most identity wallets want to present “human-friendly” representations. Examples of this include the , (".pkpass"), , etc. A resource, using something like may enable a credential representation to be shown according to the brand guidelines of the issuer, , etc.

Figure 1:

Such visual representations can also be used to quickly communicate information visually during identity exchanges, such as airline mobile boarding passes.

Figure 2: Mobile boarding passes in Apple Wallet showing different visual styles (source: )

In the , the pass at the front is for a “Gold” loyalty status member, whereas the pass at the back is for a “standard” loyalty status member. This information can be represented in a Verifiable Credential, of course, but the example here uses the Apple Wallet / Google Wallet formats to overlay a richer display.

While it’s useful to have digital credentials that can be verified cryptographically, the reality is that there are often occasions when a quick “visual check” is done instead. For example, when at an airport, an airline staff member might visually check a mobile boarding pass to direct people to the correct queue they need to join. The mobile boarding pass does get scanned at points like check-in, security, boarding etc., to digitally read the information, other scenarios where this is not done are equally valid. However, most Verifiable Credential formats do not explicitly provide such “human-friendly” forms of showing the data held in a credential.

Documents

More broadly, there are other types of resources that might be relevant for companies beyond SSI vendors, that want a way to represent information about themselves in an immutable and trustworthy way.

Many companies require documentation such as Privacy Policies, Data Protection Policies or Terms of Use to be made publicly available. Moreover, , which would typically be a text file, a , PDF etc.

Logos

Companies may want to provide authorised image logos to display across different websites, exchanges or block explorers. Examples of this include (which is used by to show logos for validators) and “” (commonly used to set the logo for websites in browser tabs).

The current uses for resources are therefore very broad across the SSI ecosystem, and in addition, for other companies that may want to use DIDs to reference relevant information on ledger. For this reason, it is essential that the SSI community strengthens the way that resources are stored, referenced and retrieved in SSI ecosystems.

In our demo for IIW, we showed an IIW logo as a resource on-ledger, being used within the body of a Verifiable Credential. In the JSON below, you will be able to see the resources being used in both the "@context" and "logo" sections.

By clicking the image below, you will see that this is actually being pulled and resolved from the cheqd ledger:

Rationale for storing resources on-ledger

What are the problems with the way resources are stored?

There are multiple approaches to decentralised identity which rely on centralised infrastructure across different technical layers. Decentralised Identifiers (DIDs): are often stored on ledgers (e.g., , , distributed storage (e.g., in ), or non-ledger distributed systems (e.g., ). Yet, DIDs can be stored on traditional centralised-storage endpoints (e.g., , .)

The issue of centralisation affects resources providing extra context and information to support Verifiable Credentials. These resources, such as schemas and revocation lists, are often stored and referenced using centralised hosting providers.

Using centralised hosting providers to store resources may have a significant difference in the longevity and authenticity of Verifiable Credentials. For example, a passport (which typically has a 5–10 year validity) issued as a Verifiable Credential anchored to a DID (regardless of whether the DID was on-ledger or not) might stop working if the credential schema, visual presentation format, or other necessary resources were stored off-ledger on traditional centralised storage.

• DIDs could be tampered by compromising the hosting provider: DIDs and DID Documents ("DIDDocs") stored at a centralised web endpoint can be compromised and replaced by malicious actors.

• Hosting providers could unilaterally cease to host particular clients: Hosting providers could terminate accounts due to factors such as non-payment of fees, violation of Terms of Service, etc.

• Single point-of-failure in resiliency: Even for highly-trusted and sophisticated hosting providers who may not present a risk of infrastructure being compromised, a service outage at the hosting provider can make a DID anchored on their systems inaccessible.

Single points of failure

Even for highly-trusted and sophisticated hosting providers who may not present a risk of infrastructure being compromised, a service outage at the hosting provider can make a resource anchored on their systems inaccessible.

The high centralisation of cloud providers and history of noteworthy outages clearly demonstrates why we should not host resources on centralised cloud storage in production environments. In Q1 of 2022, the three largest players in the cloud (AWS, Google Cloud, Microsoft Azure) dominated with .

Figure 3: Breakdown of global cloud provider market share (source: )

Beyond cloud providers, there are other events that exemplify the issuers relying on larger players. The (shown in the graph below) functionality. This highlights the risks of “contagion impact” (e.g., ) of centralised digital systems — even ones run by extremely-capable tech providers.

Figure 4: Graph showing drop in Facebook traffic from their global service outage in 2021 (source: )

Likewise, with decentralised identity, there has been excellent work to decentralise, with standards that remove the need for centralised intermediaries — notably around and the decentralised trust provided by . Yet, all of this excellent work may be eroded in practice, unless every component of an SSI ecosystem is able to maintain an equivalent level of decentralised trust. Resources are currently an area that has been centralised for the sake of convenience.

Link rot

"Link rot" happens when over time, URLs become inaccessible, either because the endpoint where the content was stored is no longer active, or the URL format itself changes. The graph below from shows degradation over time of URLs.

Figure 5: Linkrot analysis over 1996-2019 by New York Times (source: )

For this reason, keeping an up-to-date version of the links themselves is crucial. Furthermore, a study of link rot found . This can have an adverse impact on the digital longevity of Verifiable Credentials if there’s “link rot” in the resources necessary to process the credential. For this reason, projects such as ’s exist to snapshot digital ephemera before they are lost forever.

Figure 6: Pie chart showing root causes of link rot (source: )

This illustrates that link rot can affect a significant proportion of links in a relatively small amount of time, and once again, looking at how resources are currently stored in SSI ecosystems, if the resource locations are moved and the links are broken, the Verifiable Credentials relying on these resources become unusable. Therefore, resources, once defined, should be architected to be used and referenced indefinitely, without being changed.

Tamper-evident changes and censorship resistance

Finally, the centralised way that resources are currently stored and managed is not immutable, and as a result, it is liable to tampering. For example, if a hosting provider is compromised, or if malicious actors are working for the company, resources may be changed and previous resource versions may be purged from the central database.

As we move towards a new web infrastructure with Web 3 (and beyond…), and as more projects leverage blockchain and distributed ledgers, it’s important not to port the previous issues of the web, and instead find novel ways to better manage information, with longevity in mind. This is why at cheqd, we have decided to redesign the way resources are captured on the ledger.

Semantic Linkage

Solutions that do currently store schemas on ledger (e.g., Hyperledger Indy) don't have semantic linkage between old and new versions. In this instance, current ledgers allow new versions to be made but don't offer an easy way for client apps to discover linkages as they evolve over time.

Addressing risk vectors using DID-Linked Resources

We took the following design principles into consideration, along with an explanation of how we addressed them:

1. Built using existing, familiar DID Core Spec patterns: Wherever possible, our design attempts to utilise existing patterns and behaviours within the W3C DID Core specification (such as the use of DID URLs to identify resources), instead of trying to implement proprietary/custom approaches. We believe that similar designs could be adopted by other DID methods if they choose.

2. Protection against linkrot for long-term retrieval: Any Resource stored on-ledger is replicated across multiple nodes.

   1. If any individual node or endpoint is down, lookup requests can be sent to any other node on the network.

Learn more about the , and how we achieve these design principles.

Formatting a Resource

"Resources" are identified with a did:cheqd Decentralized Identifier with a Universally Unique Identifier (UUID) that acts as a permanently-accessible link to fetch the resources from the cheqd ledger. We refer to this as the "resource ID".

Using UUIDs, we can have a high level of confidence that no two identical resource IDs will ever be created. This is important for ensuring the integrity and uniqueness of each individual resource.

Figure 1: DID-linked Resource DID URL path

This will be explained further in the section on DID URL dereferencing to fetch a resource.

Understanding the DID and Collection relationship

Resources are organised into groups called "Collections". Each DID may have an associated Collection, and the Collection ID is derived from the unique identifier of the DID.

Collections can store any type of Resource, but for the purpose of this documentation we will focus on the use case where the Collection is used for storing a set of schemas.

The most important concept used in this design is that each on-ledger Collection is identified using a DID and is described using a DID Document.

The DID Document acts as metadata, providing information about the Collection, such as who is able to update it, when it was created and what are the latest and deprecated versions of Resources within the Collection.

For example, the following DID:

did:cheqd:mainnet:1f8e08a2-eeb6-40c3-9e01-33e4a0d1479d

will derive the Collection ID: 1f8e08a2-eeb6-40c3-9e01-33e4a0d1479d

Figure 2: Relationship between a DID and Resource Collection

A Collection is created using a createResource transaction, and specifying the Collection ID as the same identifier as that of the parent DID.

Note that the Collection ID may take the syntactical form of a 'Hyperledger Indy' DID identifier or may be a . This is described in the .

Creating a Resource inside a Collection, associated with a DID

To create a "DID-Linked Resource", you must already have created a 'parent' DID, from which the Collection ID can be derived. When you carry out the createResource transaction, you must:

1. Generate a new, unique UUID for the Resources

2. Specify the same Collection ID as the unique identifier of the parent DID

3. Sign the createResource transaction with the Verification Method keys of the parent DID.

This is shown in the diagram below:

Figure 3: Relationship between a DID and DID-linked Resource

Example of createResource transaction using Veramo SDK:

Linking DIDs to Resources and Collections

Multiple, DID-Linked Resources can be stored in a Collection, for example, this could be different versions of the same Resource over a period of time or semantically-linked resources. This enables unique resources to be stored directly on-ledger and be retrievable through DID resolution and dereferencing.

Once you have created a resource, the DID Document will automatically reference the resource and the collection within the didDocumentMetadata in a newly defined section called linkedResourceMetadata.

This relationship is shown in the diagram below:

Figure 4: DID Document metadata with DID-linked Resource metadata

For simplicity, we will focus on the use case where a Resource is a schema. The same logic used in fetching schemas from the ledger can be applied to any of the aforementioned types of Resources.

The syntax of a Resource metadata for a single schema is as follows:

Media Types allowed in Resources

Any (colloquially known as "file type") is allowed as an on-ledger Resource. The only restriction is that the Resource should fit within a block, which de-facto restricts it to ~190KB to fit within the ~200KB block limit. Any files larger than this are recommended to be stored and linked via long-term immutable file discovery mechanisms such as .

A based on the file extension of provided resource file. This makes it much simpler to maintain, since there is no list of file types that the cheqd ledger needs to gatekeep.

Resource Request Parameters

The following list defines which specific parameters a resource request format may contain:

Resource Response Parameters

The following list defines which specific parameters a resource response format may contain:

Example of a resolved DID with an associated Resource

Let’s take a look at a fully resolved output response for a DID with a Collection and single associated Resource:

Example of DID Document with multiple versions of the same resource

Let’s take a look at a fully resolved output response for a DID with a Collection and multiple associated Resources:

Collections are identified by a Collection ID which is a unique identifier of the linked, parent DID. Within the DID Document Metadata of the Collection DIDDoc, the Linked Resource metadata describes Resources within this Collection:

Note that the Linked Resource output above does not show the actual data / schema attributes when displaying all Resources in this Collection. It only shows Resource metadata.

This logic prevents GetResourceCollection requests returning large quantities of data, which may be stored across multiple Resources within a Collection.

In order to fetch the actual data, it is necessary to query the specific Resource, rather than the entire Collection.

For more information about the particulars of requests and responses, please refer to our .

Versioning and Archiving Resources

As shown in the examples above, there may be previous and next versions of the Resource ID.

Whenever a Resource is updated, a new UUID must be generated. The new Resource references the older version, so the UUID is effectively a version number.

Importantly, the collectionId, resourceName and the resourceType of the Resource must remain the same.

For example, a Resource with the name PassportSchema must always have the same name and resource type to be considered for previous/next version linking.

This could be used, for example, to find the version active at a particular point in time:

Query based dereferencing

Fetching resources using DID resolvers and DID URLs is hugely desirable. Up until this point, we have shown resources identified using path-based syntax.

However, query-based syntax should also be enabled to allow more granular and specific searches within a particular Collection.

To enable combined resolution/dereferencing behavior, cheqd are defining multiple query-based parameters to fetch resource or associated metadata. If a specification supports these parameters, and if a using that method includes the parameter with a valid value, then when a resolver calls the associated using that , the VDR returns the identified digital resource, not the .

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