Skip to content

Conversation

@ankurdotb
Copy link
Contributor

Key changes

This release addresses feedback regarding the current state that dealing with DID-Linked Resources (DLR) typically requires two API calls:

  1. One to resolve the DID Document and its metadata, which contains the DLR metadata too
  2. One to fetch the resource itself
  3. If just fetching a DLR, the DLR and DLR metadata need to be fetched separately

This release allows, for certain Accept header profiles, for both the DLR and its metadata to be fetched in a single call. We've also maintained backwards compatibility with current behaviour when no specific header is provided or DID Documents/DLRs fetched in the browser.

Supporting more granular ways of fetching DID Documents and DID-Linked Resources will offer developers greater control when fetching resolution/dereferencing results.

For DID Resolution

  1. Accept: application/ld+json;profile="https://w3id.org/did-resolution": Returns DID Document + DID Document metadata with DID-Linked Resource metadata
  2. Accept: application/did+json, application/did, or application/did+ld+json: Returns DID Document only, no DID Document metadata
  3. Accept: */* or accessing via browser: → Returns DID Document + DID Document metadata with DID-Linked Resource metadata
  4. Query parameter resourceMetadata=false: Returns DID Document + DID Document metadata without DID-Linked Resource metadata

For DID URL Dereferencing

  1. Accept: application/ld+json;profile="https://w3id.org/did-url-dereferencing": Returns DID-Linked Resource (Base64-encoded) and its metadata in a single response
  2. Accept: */*, specific Accept header (e.g., Accept: application/json), or accessing via browser: Keeps existing behaviour, returning only the DID-Linked Resource

General improvements

  1. When specifying multiple acceptable values in Accept header, you can now use q values to prioritise preferred IANA media types in response and this will be respected.
  2. If DID-Linked Resource queries are ambiguous, an invalidDidUrl error is now thrown instead of attempting to resolve to first matching DID-Linked Resource
  3. DID-Linked Resource metadata is now consistently returned in contentMetadata rather than contentStream. Only the actual DID-Linked Resource, if requested in body in Base64-encoding, is returned in contentStream

Full changelog

https://github.com/cheqd/did-resolver/releases/tag/v3.7.0

@BernhardFuchs
Copy link
Member

@ankurdotb @peacekeeper Version 3.7.0 of the cheqd driver with latest tag of uni-resolver-web return following error:

[internalError] Driver cannot retrieve resolve result for did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47 from http://cheqd-did-driver:8080/1.0/identifiers/did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47: No DID document consumer for media type: application/ld+json

@peacekeeper
Copy link
Member

This may be a bug in the Universal Resolver itself, I will take a look..

@ankurdotb
Copy link
Contributor Author

A bit confused indeed, so do let me know. I tried it with that Accept header on Postman and seemed to work 🤔

@ankurdotb ankurdotb changed the title build: Bump cheqd driver to v3.7.0 build: Bump cheqd driver to v3.7.2 Feb 28, 2025
@ankurdotb
Copy link
Contributor Author

Added a minor version bump to v3.7.2., which has a dependency update + a minor bugfix in one condition where the the media type was not being checked correctly.

@peacekeeper
Copy link
Member

peacekeeper commented Mar 1, 2025

@ankurdotb The driver returns something like this:

{
  "@context": "https://w3id.org/did-resolution/v1",
  "didResolutionMetadata": {
    "contentType": "application/ld+json",
    ...
  },
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://identity.foundation/.well-known/did-configuration/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "did:cheqd:mainnet:Ps1ysXP2Ae6GBfxNhNQNKN",
    ...
  },
  "didDocumentMetadata": {
    ...
  }
}

The problem is the contentType metadata property. According to https://www.w3.org/TR/did-resolution/#did-resolution-metadata, the contentType must be the media type of one of the conformant representations. At the moment, the Univeral Resolver would recognize application/did, application/did+ld+json, application/did+json, but not application/ld+json.

We could update the Universal Resolver logic to also support application/ld+json as a value here, i.e. make media types in DID Resolution work a bit more like in HTTP content negotiation (there is an open issue here).

But as a quick fix, perhaps you could update this value in the driver?

@peacekeeper
Copy link
Member

Also, I agree with everything in your comment #468 (comment), but I'm not sure if the driver actually behaves in this way.

E.g. if I try:

docker run -d -p 8131:8080 ghcr.io/cheqd/did-resolver:3.7.2
curl -H 'Accept: application/did' -X GET http://localhost:8131/1.0/identifiers/did:cheqd:mainnet:Ps1ysXP2Ae6GBfxNhNQNKN

Then the driver still returns a DID resolution result including metadata, rather than just the DID documen itself?

@ankurdotb
Copy link
Contributor Author

Yep we can update the driver, but sorry I might have misunderstood from the chat: I thought the correct resolution profile from our discussions was supposed to be Accept: application/ld+json;profile="https://w3id.org/did-resolution" and hence the content type would be application/ld+json? Or was that a typo in the Slack chat?

@ankurdotb ankurdotb changed the title build: Bump cheqd driver to v3.7.2 build: Bump cheqd driver to v3.7.4 Mar 7, 2025
@ankurdotb
Copy link
Contributor Author

@peacekeeper Hopefully resolved two issues in this latest commit (release version changed to v3.7.4):

  1. The HTTP header response type is kept to application/ld+json with the profile, the contentType in body is changed to application/did
  2. On specifically using application/did etc, I didn't realise we should also be skipping didResolutionMetadata. This is now skipped/returned as empty, but let me know if this needs to be entirely removed (not even the top-level key)

@peacekeeper
Copy link
Member

I didn't realise we should also be skipping didResolutionMetadata. This is now skipped/returned as empty, but let me know if this needs to be entirely removed

In this case you should return the plain DID document itself, NOT wrapped inside a "didDocument" key.

Wrong:

{
  "didDocument": {
    "id": "did:cheqd:mainnet:Ps1ysXP2Ae6GBfxNhNQNKN",
    "verificationMethod": [
      ....
    ]
    ....
  },
  "didResolutionMetadata": {
    "did": {}
  }
}

Correct (the plain DID document itself):

{
    "id": "did:cheqd:mainnet:Ps1ysXP2Ae6GBfxNhNQNKN",
    "verificationMethod": [
      ....
    ]
    ....
}

If you can make this additional change, I think we're done..

@ankurdotb ankurdotb marked this pull request as draft March 10, 2025 09:11
@ankurdotb
Copy link
Contributor Author

Okay thanks, that helps disambiguate - I'll mark this as draft until we get that new release ready

@ankurdotb ankurdotb marked this pull request as ready for review March 11, 2025 11:14
@ankurdotb
Copy link
Contributor Author

@peacekeeper Should be all fixed now, resetting to ready for review

@BernhardFuchs BernhardFuchs merged commit e8a4a5e into decentralized-identity:main Mar 13, 2025
5 checks passed
@ankurdotb ankurdotb deleted the cheqd-v3.7.0 branch March 13, 2025 14:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants