DID Resolution Extensions

Known Extensions for DID Resolution and Dereferencing

W3C Group Note

More details about this document
This version:
https://www.w3.org/TR/2026/NOTE-did-extensions-resolution-20261111/
Latest published version:
https://www.w3.org/TR/did-extensions-resolution/
Latest editor's draft:
https://w3c.github.io/did-extensions/resolution/
History:
https://www.w3.org/standards/history/did-extensions-resolution/
Commit history
Editors:
Manu Sporny (Digital Bazaar) (2017-present)
Markus Sabadello (Danube Tech) (2020-present), until 2025-12-10
Former editors:
Orie Steele (Transmute) (2020-2022)
Amy Guy (Digital Bazaar) (2020-2022)
Ivan Herman (W3C) (2020-2022)
Author:
The Decentralized Identifier Working Group (W3C)
Feedback:
GitHub w3c/did-extensions (pull requests, new issue, open issues)
public-did-wg@w3.org with subject line [did-extensions-resolution] … message topic … (archives)
Related Documents
DID Core
DID Core Implementation Report
DID Use Cases and Requirements

Abstract

This document serves as a collection of known DID Resolution and Dereferencing extensions.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-did-wg@w3.org ( subscribe, archives).

Portions of the work on this specification have been funded by the United States Department of Homeland Security's Science and Technology Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002, 70RSAT20T00000010, and HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.

Work on this registry has also been supported by the Rebooting the Web of Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu Sporny, Drummond Reed, Joe Andrieu, and Heather Vescent, Dmitri Zagidulin, and Dan Burnett.

This document was published by the Decentralized Identifier Working Group as a Group Note using the Note track.

This Group Note is endorsed by the Decentralized Identifier Working Group, but is not endorsed by W3C itself nor its Members.

The W3C Patent Policy does not carry any licensing requirements or commitments on this document.

This document is governed by the 18 August 2025 W3C Process Document.

1. Introduction

This section is non-normative.

This document serves as a collection of known DID Resolution and Dereferencing extensions.

1.1 The Registration Process

The registration process is described in the Decentralized Identifier Extensions.

1.2 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

2. Representations

This table provides a reference for media types and the associated specifications for producing and consuming those representations.

Media Type Specification
application/did+json DID Core
application/did+ld+json DID Core
application/did+cbor The Plain CBOR Representation

3. Representation-Specific Entries

3.1 JSON

These are entries in DID documents that are specific to the JSON representation.

(No entries yet)

3.2 JSON-LD

These are entries in DID documents that are specific to the JSON-LD representation.

3.2.1 @context

Normative Definition
DID Core

The following values are acceptable values for the @context entry as a JSON String or first item of a JSON Array, represented as a JSON String.

@context Values Specification Version
https://www.w3.org/ns/did/v1 DID Core 1.0 Working draft
Example 1: Example of @context in the JSON-LD representation
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://example.com/blockchain-identity/v1"
  ],
  ...
}

3.3 CBOR

These are entries in DID documents that are specific to the CBOR representation.

(No entries yet)

4. DID Resolution Options

These properties contain information pertaining to the DID resolution request.

4.1 accept

Normative Definition
DID Core
Example 2: Example of accept metadata property
{
  "accept": "application/did+ld+json"
}

5. DID Resolution Metadata

These properties contain information pertaining to the DID resolution response.

5.1 contentType

Normative Definition
DID Core
Example 3: Example of contentType metadata property
{
  "contentType": "application/did+ld+json"
}

5.2 error

Normative Definition
DID Resolution, DID Core v1.0
Example 4: Example of error metadata property
{
  "error": {
    "type": "https://www.w3.org/ns/did#NOT_FOUND",
    "title": "DID not found"
  }
}

5.2.1 invalidDid

Normative Definition URL
DID Resolution, DID Core v1.0 https://www.w3.org/ns/did#INVALID_DID
Example 5: Example of invalidDid error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#INVALID_DID",
    "title": "Invalid DID"
  }
}

5.2.2 INVALID_DID_DOCUMENT

Normative Definition URL
DID Resolution https://www.w3.org/ns/did#INVALID_DID_DOCUMENT
Example 6: Example of INVALID_DID_DOCUMENT error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#INVALID_DID_DOCUMENT",
    "title": "Invalid DID document"
  }
}

5.2.3 notFound

Normative Definition URL
DID Resolution, DID Core v1.0 https://www.w3.org/ns/did#NOT_FOUND
Example 7: Example of notFound error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#NOT_FOUND",
    "title": "DID not found"
  }
}

5.2.4 representationNotSupported

Normative Definition URL
DID Resolution, DID Core v1.0 https://www.w3.org/ns/did#REPRESENTATION_NOT_SUPPORTED
Example 8: Example of representationNotSupported error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#REPRESENTATION_NOT_SUPPORTED",
    "title": "Representation not supported"
  }
}

5.2.5 methodNotSupported

Normative Definition URL
DID Resolution https://www.w3.org/ns/did#METHOD_NOT_SUPPORTED
Example 9: Example of methodNotSupported error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#METHOD_NOT_SUPPORTED",
    "title": "DID method not supported"
  }
}

5.2.6 INVALID_OPTIONS

Normative Definition URL
DID Resolution https://www.w3.org/ns/did#INVALID_OPTIONS
Example 10: Example of INVALID_OPTIONS error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#INVALID_OPTIONS",
    "title": "Invalid options"
  }
}

5.2.7 internalError

Normative Definition URL
DID Resolution https://www.w3.org/ns/did#INTERNAL_ERROR
Example 11: Example of internalError error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#INTERNAL_ERROR",
    "title": "Internal error"
  }
}

5.2.8 FEATURE_NOT_SUPPORTED

Normative Definition URL
DID Resolution https://www.w3.org/ns/did#FEATURE_NOT_SUPPORTED
Example 12: Example of FEATURE_NOT_SUPPORTED error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#FEATURE_NOT_SUPPORTED",
    "title": "Feature not supported"
  }
}

5.2.9 invalidPublicKey

Deprecated

This error is deprecated. Its definition was removed from DID Resolution in January 2026 and no other specification defines it.

Normative Definition URL
DID Resolution (28 November 2024 Working Draft) None defined
Example 13: Example of invalidPublicKey error value
{
  "error": "invalidPublicKey"
}

5.2.10 invalidPublicKeyLength

Deprecated

This error is deprecated. Its definition was removed from DID Resolution in January 2026 and no other specification defines it.

Normative Definition URL
DID Resolution (28 November 2024 Working Draft) None defined
Example 14: Example of invalidPublicKeyLength error value
{
  "error": "invalidPublicKeyLength"
}

5.2.11 invalidPublicKeyType

Deprecated

This error is deprecated. Its definition was removed from DID Resolution in January 2026 and no other specification defines it.

Normative Definition URL
DID Resolution (28 November 2024 Working Draft) None defined
Example 15: Example of invalidPublicKeyType error value
{
  "error": "invalidPublicKeyType"
}

5.2.12 unsupportedPublicKeyType

Deprecated

This error is deprecated. Its definition was removed from DID Resolution in January 2026 and no other specification defines it.

Normative Definition URL
DID Resolution (28 November 2024 Working Draft) None defined
Example 16: Example of unsupportedPublicKeyType error value
{
  "error": "unsupportedPublicKeyType"
}

5.2.13 notAllowedVerificationMethodType

Normative Definition URL
DID Spec Extension: notAllowedVerificationMethodType None defined
Example 17: Example of notAllowedVerificationMethodType error value
{
  "error": "notAllowedVerificationMethodType"
}

5.2.14 notAllowedKeyType

Normative Definition URL
DID Spec Extension: notAllowedKeyType None defined
Example 18: Example of notAllowedKeyType error value
{
  "error": "notAllowedKeyType"
}

5.2.15 notAllowedMethod

Normative Definition URL
DID Spec Extension: notAllowedMethod None defined
Example 19: Example of notAllowedMethod error value
{
  "error": "notAllowedMethod"
}

5.2.16 notAllowedCertificate

Normative Definition URL
DID Spec Extension: notAllowedCertificate None defined
Example 20: Example of notAllowedCertificate error value
{
  "error": "notAllowedCertificate"
}

5.2.17 notAllowedLocalDuplicateKey

Normative Definition URL
DID Spec Extension: notAllowedLocalDuplicateKey None defined
Example 21: Example of notAllowedLocalDuplicateKey error value
{
  "error": "notAllowedLocalDuplicateKey"
}

5.2.18 notAllowedLocalDerivedKey

Normative Definition URL
DID Spec Extension: notAllowedLocalDerivedKey None defined
Example 22: Example of notAllowedLocalDerivedKey error value
{
  "error": "notAllowedLocalDerivedKey"
}

5.2.19 notAllowedGlobalDuplicateKey

Normative Definition URL
DID Spec Extension: notAllowedGlobalDuplicateKey None defined
Example 23: Example of notAllowedGlobalDuplicateKey error value
{
  "error": "notAllowedGlobalDuplicateKey"
}

6. DID Dereferencing Metadata

These properties contain information pertaining to the DID dereferencing response.

6.1 error

Normative Definition
DID Resolution, DID Core v1.0
Example 24: Example of error metadata property
{
  "error": {
    "type": "https://www.w3.org/ns/did#NOT_FOUND",
    "title": "Not found"
  }
}

6.1.1 invalidDidUrl

Normative Definition URL
DID Resolution, DID Core v1.0 https://www.w3.org/ns/did#INVALID_DID_URL
Example 25: Example of invalidDidUrl error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#INVALID_DID_URL",
    "title": "Invalid DID URL"
  }
}

6.1.2 notFound

Normative Definition URL
DID Resolution, DID Core v1.0 https://www.w3.org/ns/did#NOT_FOUND
Example 26: Example of notFound error value
{
  "error": {
    "type": "https://www.w3.org/ns/did#NOT_FOUND",
    "title": "Not found"
  }
}

7. DID Document Metadata

These properties contain information pertaining to the DID document itself, rather than the DID subject.

7.1 created

Issue 1

See DID Core #203.

Normative Definition JSON-LD
DID Core DID Core
Example 27: Example of created property
{
  "created": "2019-03-23T06:35:22Z"
}

7.2 updated

Issue 2

See DID Core #203.

Normative Definition JSON-LD
DID Core DID Core
Example 28: Example of updated property
{
  "updated": "2023-08-10T13:40:06Z"
}

7.3 deactivated

Normative Definition JSON-LD
DID Core DID Core
Example 29: Example of deactivated property
{
  "deactivated": true
}

7.4 nextUpdate

Normative Definition JSON-LD
DID Core DID Core
Example 30: Example of nextUpdate property
{
  "nextUpdate": "2023-08-10T13:40:06Z"
}

7.5 versionId

Normative Definition JSON-LD
DID Core DID Core
Example 31: Example of versionId property
{
  "versionId": "bafyreifederejlobaec6kwpl2mc3tw7qk3j3ey4uytkbiw2qw7dzylud6i"
}

7.6 nextVersionId

Normative Definition JSON-LD
DID Core DID Core
Example 32: Example of nextVersionId property
{
  "nextVersionId": "bafyreifederejlobaec6kwpl2mc3tw7qk3j3ey4uytkbiw2qw7dzylud6i"
}

7.7 equivalentId

Normative Definition JSON-LD
DID Core DID Core
Example 33: Example of equivalentId property
{
  "equivalentId": ["did:example:ABC", "did:example:Abc"]
}

7.8 canonicalId

Normative Definition JSON-LD
DID Core DID Core
Example 34: Example of canonicalId property
{
  "canonicalId": "did:example:ABC"
}

8. Parameters

8.1 hl

Normative Definition
DID Core
Example 35: Example of hl parameter
did:example:123?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e

8.2 service

Normative Definition
DID Core
Example 36: Example of service parameter
did:example:123?service=agent

8.3 versionId

Normative Definition
DID Core
Example 37: Example of versionId parameter
did:example:123?versionId=4

8.4 versionTime

Normative Definition
DID Core
Example 38: Example of versionTime parameter
did:example:123?versionTime=2016-10-17T02:41:00Z

8.5 relativeRef

Normative Definition
DID Core
Example 39: Example of relativeRef parameter
did:example:123?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest%23intro

8.6 initialState

Normative Definition
DID Spec Extensions by DIF
Example 40: Example of initialState parameter
did:example:123?initialState=eyJkZWx0YV9oYXNoIjoiRWlDUlRKZ2Q0U0V2YUZDLW9fNUZjQnZJUkRtWF94Z3RLX3g...

8.7 transformKeys

Normative Definition
DID Spec Extensions by DIF
Example 41: Example of transformKeys parameter
did:example:123?transformKeys=jwk

8.8 signedIetfJsonPatch

Normative Definition
DID Spec Extensions by DIF
Example 42: Example of signedIetfJsonPatch parameter
did:example:123?signedIetfJsonPatch=eyJraWQiOiJkaWQ6ZXhhbXBsZTo0NTYjX1FxMFVMMkZxNjUxUTBGamQ2VH...

8.9 resource

Normative Definition
DID URL Resource Parameter Specification
Example 43: A DID URL with a 'resource' DID parameter
did:foo:21tDAKCERh95uGgKbJNHYp?resource=true

A. References

A.1 Informative references

[DID-EXTENSIONS]
Decentralized Identifier Extensions. Manu Sporny. Decentralized Identifier Working Group. W3C Working Group Note. URL: https://www.w3.org/TR/did-extensions/