diff --git a/index.html b/index.html index 6439910..aa3c507 100644 --- a/index.html +++ b/index.html @@ -200,18 +200,23 @@

Implementer Overview

(e.g., `contentType`, proof, versioning) which an application can use to validate a user's cryptographic keys, service endpoints, or status.

- For example, a wallet app could resolve did:example:123?versionTime=2021-05-10T17:00:00Z - using the `versionTime` parameter to retrieve the state of that DID at a past time, or a client could - dereference a DID URL - like did:example:123?service=files&relativeRef=/resume.pdf - (see here for detailed example) - to fetch a user's resume stored via a service declared in the DID document. + For example, a wallet app could resolve + did:example:123?versionTime=2021-05-10T17:00:00Z + (see here for detailed example) + using the `versionTime` parameter to retrieve the state of that DID + at a past time, or a client could dereference a DID URL like + did:example:123/resume.pdf (see + here for detailed example) to fetch a + user's resume stored via a service declared in the DID document.

- Further, the specification's DID URL dereferencing algorithm shows how - a client can follow a fragment (e.g., #key-1) to extract a particular verification method from - the DID document (see here for detailed example). - In practice, implementers validate their resolver against the + Further, the specification's DID + URL dereferencing algorithm shows how a client can follow a + fragment (e.g., #key-1) to extract a particular + verification method + from the DID document (see here + for detailed example). In practice, implementers validate their + resolver against the DID Resolution Test Suite which exercises normative MUSTs and error conditions (such as invalid DIDs, deactivated DIDs, unsupported methods, relative URL expansion, etc.) to ensure that client applications can reliably depend on correct resolution behavior @@ -303,159 +308,6 @@

Terminology

-
-

DID Parameters

- -

- The DID URL syntax supports a simple format for parameters - (see section Query - in [[DID-CORE]]). Adding a DID - parameter to a DID URL means that the parameter becomes part of the - identifier for a resource. -

- - 
-did:example:123?versionTime=2021-05-10T17:00:00Z
-
- - 
-did:example:123?service=files&relativeRef=/resume.pdf
-
- -

- Some DID parameters are completely independent of any specific DID - method and function the same way for all DIDs. Other DID parameters - are not supported by all DID methods. Where optional parameters are - supported, they are expected to operate uniformly across the DID methods - that do support them. The following table provides common DID parameters that - function the same way across all DID methods. Support for all - DID Parameters is OPTIONAL. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Parameter Name - - Description -
- service - - Identifies a service from the DID document by service ID. - If present, the associated value MUST be an ASCII string. -
- serviceType - - Identifies a set of one or more services from the DID document by service type. - If present, the associated value MUST be an ASCII string. -
- relativeRef - - A relative URI reference according to RFC3986 Section 4.2 that identifies a - resource at a service endpoint, which is selected from a DID - document by using the service parameter. - If present, the associated value MUST be an ASCII string and MUST use percent-encoding for - certain characters as specified in RFC3986 - Section 2.1. -
- versionId - - Identifies a specific version of a DID document to be resolved (the - version ID could be sequential, or a UUID, or method-specific). - If present, the associated value MUST be an ASCII string. -
- versionTime - - Identifies a certain version timestamp of a DID document to be resolved. - That is, the most recent version of the DID document that was valid for a DID - before the specified `versionTime`. If present, the associated value - MUST be an ASCII string which is a valid XML - datetime value, as defined in section 3.3.7 of W3C XML Schema Definition Language - (XSD) 1.1 Part 2: Datatypes [[XMLSCHEMA11-2]]. This datetime value MUST be - normalized to UTC 00:00:00 and without sub-second decimal precision. - For example: 2020-12-20T19:17:47Z. -
- hl - - A resource hash of the DID document to add integrity protection, as - specified in [[?HASHLINK]]. This parameter is non-normative. - If present, the associated value MUST be an - ASCII string. -
- -

- Implementers as well as DID method specification authors might use - additional DID parameters that are not listed here. For maximum - interoperability, it is RECOMMENDED that DID parameters use the DID - Document Properties Extensions mechanism [[?DID-EXTENSIONS-PROPERTIES]], to avoid collision - with other uses of the same DID parameter with different semantics. -

- -

- DID parameters might be used if there is a clear use case where the parameter - needs to be part of a URL that references a resource with more - precision than using the DID alone. It is expected that DID parameters - are not used if the same functionality can be expressed by passing - input metadata to a DID resolver. -

- -

- The DID resolution and the DID URL dereferencing functions can - be influenced by passing or - to a DID resolver that are - not part of the DID URL. This is comparable to - HTTP, where certain parameters could either be included in an HTTP URL, or - alternatively passed as HTTP headers during the dereferencing process. The - important distinction is that DID parameters that are part of the DID - URL should be used to specify what resource is being - identified, whereas input metadata that is not part of the DID URL - should be used to control how that resource is resolved or - dereferenced. -

- -
-

DID Resolution

@@ -1246,334 +1098,780 @@

DID URL Content Metadata

-
-

DID URL Dereferencing Algorithm

-

The following DID URL dereferencing algorithm MUST be implemented by a conformant DID resolver. - In accordance with [[RFC3986]], it consists of the following three steps: resolving the DID; dereferencing the - resource; and dereferencing the fragment (only if the input DID URL contains a DID fragment):

+
+

DID URL Components Handling

-
-

Dereferencing the Resource

-
    -
  1. Validate that the input DID URL conforms to the `did-url` rule of the - DID URL Syntax. - If not, the DID URL dereferencer MUST return the following result: -
      -
    1. dereferencingMetadata: error object with type set to INVALID_DID_URL
      2. -
    2. contentStream: null
      3. -
    3. contentMetadata: «[ ]»
      4. +

      + A DID URL consists of a DID, optionally followed by + additional URL components — any combination of a path, zero or more query + parameters, and/or a fragment identifier — as defined in + RFC3986. + This section defines how these components MUST be + interpreted by DID Resolvers when dereferencing a DID URL. +

      + +

      + The interpretation of DID URL components is conceptually similar to + that of HTTP URLs having the same components: +

      + +
        +
      • + A DID Resolver is comparable to a web server — responsible + for interpreting the request and returning a representation of the + identified resource. Unlike general-purpose HTTP servers, DID + Resolvers are more constrained in their behavior, typically + implementing DID Method-specific resolution rules. +
        • +
      • + A client of a DID Resolver is comparable to a web browser — + responsible for constructing the DID URL and processing the + response. DID Resolver clients are generally more flexible than + browsers, applying deployment-specific handling of the resolved + resource by media type, including metadata and fragment (if any). +
        • +
      + +

      + The similarity ends there. DID Resolvers do not support arbitrary + server logic or content negotiation. Instead, the interpretation of + DID URL components is deterministic and governed by this + specification, the applicable DID method specification, and + any DID Document Properties Extensions + [[?DID-EXTENSIONS-PROPERTIES]] supported by the DID Resolver. +

      + +

      + This section describes the structure, constraints, and required + handling of each DID URL component. These rules form the basis for + the DID URL dereferencing algorithm. +

      + +
      +

      Fragment

      + +

      + A DID URL MAY include not more than one + fragment component, as specified in + RFC3986 Section 3.5. If + present, the fragment component appears after all other components + of the DID URL. +

      + +

      + As with HTTP/S dereferencing, + the fragment is not processed by the DID Resolver. Instead, + its interpretation is the responsibility of the client that receives + the dereferenced resource from the resolver. The meaning of the + fragment depends on the media type of the resolved content and may + be used to reference a specific node in a DID Document or a part of + another structured resource. For example, if the resolved resource + is a DID Document, the fragment may be used to identify a + verification method + to be used by the client in processing a cryptographic signature. +

      + +

      + DID Method-specific and DID Document Properties Extensions + [[?DID-EXTENSIONS-PROPERTIES]] MUST define guidance + for how a DID Resolver Client should process a node in a DID Document + that is referenced by a fragment. Such guidance can specify + how to interpret the node's structure, expected data type, or its + use in further processing (for example, verifying a signature or + retrieving related resources). +

      +
      + +
      +

      Query Parameters

      + +

      + A DID URL MAY include one or zero + query component(s), which, if present, MAY include + zero or more query parameters, as defined in + RFC3986 Section 3.4. Query + parameters appear after the DID and any path component, and their + structure and encoding MUST follow standard URL syntax conventions. + Their interpretation depends on the context in which the DID URL is + used and can influence the dereferencing result. +

      + +

      + Unlike HTTP query parameters, which are interpreted by customized web server + implementations, DID parameters in DID + URLs MUST have predefined semantics. A DID Resolver MUST process + only recognized query parameters — specifically those defined in + this specification (see the DID Parameter + definitions), the applicable DID method specification, and/or + DID Document Properties Extensions [[?DID-EXTENSIONS-PROPERTIES]]. + All other query parameters MAY be passed through unchanged for + downstream processing, such as dereferencing a + DID URL path. +

      + +

      + Query parameters may affect dereferencing behavior, such as by + specifying a versioned resource or by influencing how a path is + to be processed. The impact of specific query parameters defined in this + specification in combination with a DID URL path is described + in the next section of this specification. +

      +
      + +
      +

      Path

      + +

      + A DID URL MAY include not more than one path component, as defined in + RFC3986 Section 3.3. If + present, the path component appears immediately after the DID and + before any query or fragment component(s). Its structure and encoding + MUST conform to URI syntax rules. +

      + +

      When a DID URL path is present, the following processing steps + MUST be followed:

      + +
        +
      1. + Resolve the DID portion of the DID URL, applying all + DID Resolution-specific DID Parameters to + retrieve a DID Document. +
          +
        1. If resolution of the DID Document fails, the + resolver MUST return an error and abort the + dereferencing process.
        2. -
      2. Obtain the DID document for the input DID by executing the - DID resolution algorithm as defined in . All - dereferencing options and all - - DID parameters of the input DID URL MUST be passed as resolution options to the - DID Resolution algorithm.
        3. -
      3. If the input DID does not exist in the VDR, the DID URL dereferencer - MUST return the following result: -
          -
        1. dereferencingMetadata: error object with type set to NOT_FOUND
          2. -
        2. contentStream: null
          3. -
        3. contentMetadata: «[ ]»
          4. -
        +
      4. Extract the path component from the DID URL.
        5. +
      5. + If the DID Method specifies its own path handling + algorithm, it MUST be applied, and the rest of this + algorithm skipped. Creators of DID method + specifications are encouraged to use this algorithm where + possible to increase interoperability.
        6. -
      6. Otherwise, the didDocument result of the DID resolution algorithm is called the resolved DID document.
        7. -
      7. If present, separate the DID fragment from the input DID URL and continue - with the adjusted input DID URL.
        8. -
      8. If the input DID URL contains no DID path and no DID query: - 
        did:example:1234
        - The DID URL dereferencer MUST return the resolved DID document and - resolved as follows: -
          -
        1. dereferencingMetadata: «[ ... ]»
          2. -
        2. contentStream: resolved DID document
          3. -
        3. contentMetadata: «[ resolved DID document metadata ]»
          4. -
        +
      9. + Match the extracted path against the prefix + attribute of each relevant service entry in the + DID Document that includes such an attribute. + If the service and/or serviceType + DID Parameters are + present, the DID Resolver MUST consider only services + with the respectively specified id and/or + type values. Otherwise, all + service entries MUST be considered in the + matching process. In matching the path and + prefix, the DID Resolver MUST track the + length of the match for each service.
        10. -
      10. If the input DID URL contains the - DID parameter hl: - 
        did:example:1234?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e
        -

        TODO: Specify the algorithm for processing the `hl` DID parameter.

        +
      11. + Select the service with the longest matching prefix. +
          +
        1. If two or more services have the same + longest matching prefix, the resolver + MUST fail resolution with an + appropriate error.
          2. +
        2. If no matching service is found, the resolver + MUST return an error indicating that no + applicable service was found.
          3. +
        12. -
      12. If the input DID URL contains the - - DID parameter service and/or the - DID parameter serviceType, and optionally the - DID parameter relativeRef: - 
        did:example:1234?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest
        -
          -
        1. From the resolved DID document, select all - services which fulfill the following conditions: -
            -
          1. If the input DID URL contains the - DID parameter service: - Select the service if its id - property matches the value of the service DID parameter. If the id - property or the service DID parameter or both contain relative - references, the corresponding absolute URIs MUST be resolved and used for determining - the match, using the rules specified in RFC3986 Section 5: Reference Resolution - and in section Relative DID URLs in [[[DID-CORE]]].
            2. -
          2. If the input DID URL contains the - DID parameter serviceType: - Select the service if its type - property matches the value of the serviceType DID parameter.
            3. -
          - The selected services are a list called the selected services. -
          2. -
        2. If the input DID URL contains the - DID parameter relativeRef: -
            -
          1. For each selected service: -
              -
            1. If the value of the serviceEndpoint property of the selected service - is a map, skip this selected service.
              2. -
            2. If the value of the serviceEndpoint property of the selected service - is a string, add this value to a list of - selected service endpoint URLs.
              3. -
            3. If the value of the serviceEndpoint property of the selected service - is a set, add all its items that are strings - to a list of selected service endpoint URLs.
              4. -
            -
            2. -
          2. For each selected service endpoint URL, execute the algorithm specified in - RFC3986 Section 5: Reference Resolution as follows: -
              -
            1. The base URI value is the selected service endpoint URL.
              2. -
            2. The relative reference is the value of the - DID parameter relativeRef.
              3. -
            3. Update the selected service endpoint URL to - the result of the "Reference Resolution" algorithm.
              4. -
            -
            -

            - Resolving a service endpoint — particularly one that is a DID — might - result in a resolution cycle, which is a set of steps that result in - an infinite loop. For example, a service endpoint might indirectly point - back through a sequence of resolutions to a previously dereferenced identifier. - A DID resolver recursively resolving a service endpoint is advised - to detect and handle such a cycle to prevent an infinite loop or resolution failure. - For further guidance, see Section Resolution Cycles. -

            -
            -
            3. -
          -
          3. -
        3. If the accept input DID dereferencing option - is missing, or if its value is the Media Type of a representation of a DID document: -
            -
          1. Update the services in the resolved DID document to contain only the - selected services.
            2. -
          2. Return the following result: -
              -
            1. dereferencingMetadata: «[ ... ]»
              2. -
            2. content: resolved DID document with selected services
              3. -
            3. contentMetadata: «[ resolved DID document metadata ]»
              4. -
            -
            3. -
          -
          4. -
        4. If the value of the accept input DID resolution option - is text/uri-list: -
            -
          1. Return the following result: -
              -
            1. dereferencingMetadata: «[ ... ]»
              2. -
            2. content: « selected service endpoint URLs »
              3. -
            3. contentMetadata: «[ "contentType" → "text/uri-list", ... ]»
              4. -
            -
            2. -
          -
          5. -
        5. Otherwise, return the following result: -
            -
          1. dereferencingMetadata: error object with type set to REPRESENTATION_NOT_SUPPORTED
            2. -
          2. content: null
            3. -
          3. contentMetadata: «[ ]»
            4. -
          +
        6. + Use the type of the selected + service to determine how the + DID URL path is to be used in assembling the URL of the + resource to be resolved. The algorithm for assembling this + URL MUST be defined in the corresponding service type + specification. A service type specification MAY appear in + the DID Service + Types section of this document, the applicable DID + method specification, or in the DID Document + Properties Extensions [[?DID-EXTENSIONS-PROPERTIES]]. +
            +
          1. + The FileService type is currently the + only service type defined in this specification. See + the FileService + Service Type section for its definition.
          7. - -
        7. Otherwise, if the input DID URL contains a DID path and/or DID query: - 
          did:example:1234/custom/path?customquery
          -
            -
          1. The applicable DID method MAY specify how to dereference - the DID path and/or DID query of the input DID URL. - 
            did:example:1234/resources/1234
            -
            2. -
          2. An extension specification MAY specify how to dereference - the DID path of the input DID URL. - 
            did:example:1234/whois
            -
            3. -
          3. An extension specification MAY specify how to dereference - the DID query of the input DID URL. - 
            did:example:1234?transformKey=JsonWebKey
            -
            4. -
          4. The client MAY be able to dereference the input DID URL - in an application-specific way.
            5. -
          -
          8. -
        8. If neither this algorithm, nor the applicable DID method, nor an extension, nor the client - is able to dereference the input DID URL, return the following result: -
            -
          1. dereferencingMetadata: error object with type set to NOT_FOUND
            2. -
          2. contentStream: null
            3. -
          3. contentMetadata: «[ ]»
            4. -
          -
          9. +
        9. Return the assembled URL for processing.
        +
        +
        Examples
        + +

        Example 1 — Basic path resolution using a + FileService with a root (/) prefix

        + + 
        +		// DID URL:
+		did:web:example.com/path/to/file.txt
+
+		// DID Document service section:
+		{
+		"service": [
+			{
+			"type": "FileService",
+			"serviceEndpoint": "https://example.com/",
+			"prefix": "/"
+			}
+		]
+		}
+
+		// Resulting URL:
+		https://example.com/path/to/file.txt
+
        + +

        Example 2 — Path maps directly to a single resource + (e.g., a Verifiable Presentation describing the DID + subject)

        + + 
        +		// DID URL:
+		did:webvh:example.com/whois
+
+		// DID Document service section:
+		{
+		"service": [
+			{
+			"type": "FileService",
+			"serviceEndpoint": "https://example.com/whois.vp",
+			"prefix": "/whois"
+			}
+		]
+		}
+
+		// Resulting URL:
+		https://example.com/whois.vp
+
        + +

        Example 3 — Use of a non-FileService type that performs + content verification + (ExampleVerifiedFileService)

        + +

        + This demonstrates a (currently) fictitious service type that + behaves like FileService, but with additional + content verification logic. The final segment of the DID URL + path is treated as a hash, removed before URL assembly, and used + to verify the integrity of the resolved content. +

        + + 
        +		// DID URL:
+		did:web:example.com/example/resume.pdf/<hash>
+
+		// DID Document service section:
+		{
+		"service": [
+			{
+			"type": "ExampleVerifiedFileService",
+			"serviceEndpoint": "https://example.com/example/files/",
+			"prefix": "/example/"
+			}
+		]
+		}
+
+		// Resulting URL:
+		https://example.com/example/files/resume.pdf
+
        + +

        + The resource is resolved from the assembled URL. Its content is + hashed and compared with the <hash> value from the DID URL + path to verify integrity. +

        + +

        Example 4 — Multiple services supporting different types + of resources under distinct path prefixes

        + +

        + This example shows a DID Document with two service entries: one + using FileService for general file access, and + another using the ExampleVerifiedFileService from + the previous example for integrity-verified files. The path + prefix determines which service to use. +

        + + 
        +		// DID URLs:
+		did:web:example.com/path/to/file.txt
+		did:web:example.com/example/resume.pdf/<hash>
+
+		// DID Document service section:
+		{
+		"service": [
+			{
+			"type": "FileService",
+			"serviceEndpoint": "https://example.com/",
+			"prefix": "/"
+			},
+			{
+			"type": "ExampleVerifiedFileService",
+			"serviceEndpoint": "https://example.com/example/files/",
+			"prefix": "/example/"
+			}
+		]
+		}
+
+		// Resulting URLs:
+		https://example.com/path/to/file.txt
+		https://example.com/example/files/resume.pdf (with hash verification after resolution)
+
        +
      +
-
-

Dereferencing the Fragment

-

If the input DID URL contains a DID fragment, - then dereferencing of the fragment is dependent - on the media type ([[RFC2046]]) of the resource, i.e., on the result of - .

-
    -
  1. If the result of is an output DID document, - and the input DID URL dereferencing options contain the - verificationRelationship option: -
      -
    1. - Let verificationRelationship be the value of the verificationRelationship - option. -
      2. -
    2. - Let verificationMethod be the result of dereferencing the - DID fragment from the output DID document according to the - rules of the media type of the DID document. -
      3. -
    3. - If verificationMethod is not a conforming verification method, - an error MUST be raised and SHOULD convey an error type of - INVALID_VERIFICATION_METHOD. -
      4. -
    4. - If verificationMethod is not associated, either by reference - (URL) or by value (object), with the verification relationship array in the - output DID document identified by verificationRelationship, - an error MUST be raised and SHOULD convey an error type of - - INVALID_RELATIONSHIP_FOR_VERIFICATION_METHOD. -
      5. -
    5. - Return the verificationMethod. -
      6. +
      +

      DID URL Dereferencing Algorithm

      +

      + This section defines the normative algorithm for dereferencing a + DID URL into a resource. It builds on the rules in the DID URL Components Handling section of + this specification. +

      +
        +
      1. + Parse the DID URL into the following components: +
          +
        • did
          • +
        • path
          • +
        • query parameters (stored as a working set qp)
          • +
        • fragment
          • +
        +
        2. + +
      2. + Handle Fragments: +
          +
        • As noted in the DID URL + fragment handling section, if a DID URL + contains a fragment, a DID Resolver SHOULD NOT process + or interpret it. Fragment handling is the client's + responsibility, based on the resolved document and its media + type.
          • +
        +
        3. + +
      3. + Resolve the DID: +
          +
        1. Identify and apply DID + parameters from qp + that affect DID Resolution (e.g., versionId, + versionTime), + including any DID Method-specific and DID Document + Property Extension [[?DID-EXTENSIONS-PROPERTIES]] DID parameters that are understood by the + DID Resolver.
          2. +
        2. Use these to resolve the did into a + didDocument and + didResolutionMetadata.
          3. +
        3. If resolution fails, return an error and abort + dereferencing.
          4. +
        4. Remove any consumed DID + parameters from the + qp working set.
        -
        4. -
      4. If the result of is a selected service endpoint URL, - and the input DID URL contains a DID fragment: - 
        did:example:1234?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest#intro
        -
          -
        1. If the selected service endpoint URL - contains a fragment component, raise an error.
          2. -
        2. Append the DID fragment to the select service endpoint URL. In other words, - the select service endpoint URL "inherits" the DID fragment of the - input DID URL.
          3. -
        3. Return the select service endpoint URL.
          4. + + +
        4. + No Path Component: + If no path is present, resolution is + complete and the path-handling step is skipped. +
          5. + +
        5. + With Path Component: +
            +
          1. Construct a target URL using the + DID URL path resolution rules.
            2. +
          2. Remove any consumed query parameters from the + qp working set.
            3. +
          3. If there are unused query parameters in qp, + add them to the constructed URL as query parameters, + ensuring they are formatted according to RFC3986 Section + 3.4.
            4. +
          4. Attempt to resolve the resulting URL to retrieve the + resource and metadata to be returned to the client.
            5. +
          5. If the resolution of the URL fails, an error + MUST be returned.
            6. +
          6. If the DID Resolver is unable to resolve the + URL, an error MUST be returned.
            7. + +
            +

            + Resolving an assembled URL from a path might result in a + resolution cycle, which is a set of steps + that result in an infinite loop. For example, a URL + assembled from a path might indirectly point back + through a sequence of resolutions to a previously + dereferenced URL. A DID resolver is expected to + detect and handle recursive cycles when resolving a URL + assembled from a path, to prevent an infinite loop or + other resolution failure. For further guidance, see + Section Resolution + Cycles. +

            +
            +
          +
          6. + +
        6. + Return the dereferencing result: +
            +
          1. + If the resolution result is a DID Document, + return the following: +
              +
            • content: the resolved DID document + with selected services
              • +
            • contentMetadata: metadata about the + resolved DID document
              • +
            • dereferencingMetadata: any metadata + about the dereferencing process
              • +
            2. -
          2. Otherwise, dereference the DID fragment as defined by the media type ([[RFC2046]]) of the resource. - For example, if the resource is a representation of a DID document with media type application/did, then - the fragment is treated according to the rules associated with the - JSON-LD 1.1: application/ld+json media type - [JSON-LD11]. +
          3. + If the resolution result is a resource resolved via DID URL path processing, return the following: +
              +
            • content: the resolved resource
              • +
            • contentType: the media type of the + resolved resource
              • +
            • dereferencingMetadata: any metadata + about the dereferencing process
              • +
            4. -
          +
        +
        5. +
      +
      -

      - This use of the DID fragment is consistent with the definition of the fragment identifier in - [[RFC3986]]. It identifies a secondary resource which is a subset of the primary resource - (the DID document). -

      +
      +

      Query Parameters and Service Types

      +

      This section defines the set of DID URLquery parameters and + service types that are reserved for use within the + DID Resolution algorithm and DID URL + dereferencing process defined in this specification.

      +

      These values are not DID Method-specific. All DID + Methods that are capable of implementing these query parameters and + service types SHOULD recognize and correctly process + them. DID Methods that do not support the capabilities required for a + specific query parameter (e.g., historical DID Document version + resolution) SHOULD recognize these query parameters and + return an appropriate error.

      + +
      +

      Query Parameters

      + +
      +
      versionID
      +

      Identifies a specific version of a DID Document to be + resolved. If present, the associated value MUST be + an ASCII string. If the DID Method does not support updating + or the tracking of DID Document versions, or if the specified + version does not match any DID Document's + versionId property, the DID Resolver + MUST return a Not Found error + indicating that the requested version could not be found.

      +

      Example: did:example:123456789abcdefghi?versionId=5e3b
      + Resolves the DID Document with the specific version ID "5e3b".

      +
      + +
      +
      versionTime
      +

      Identifies a point in time to resolve the version of the + DID Document active at that timestamp. The value + MUST be a valid XML datetime normalized to UTC and + without sub-second precision. If the DID Method does not + support updating or the tracking of DID Document versions or + version times, or if the DID did not exist at the specified time the + DID Resolver MUST return a Not Found error + indicating that the requested version could not be found.

      +

      Example: did:example:123456789abcdefghi?versionTime=2025-10-01T12:00:00Z
      + Resolves the DID Document valid on October 1, 2025 at noon UTC.

      +
      + +
      +
      service
      +

      Indicates that only the service entry or entries with the specified + id are to be considered when processing the path component of a + DID URL. If present, each value MUST be an ASCII string + that is percent-encoded as required by + RFC3986 Section 2.1, and + MAY be either a relative or absolute URI reference. The + service query parameter MAY appear multiple times + in a DID URL. If no matching services are found, the + dereferencing process MUST fail.

      +

      A service query parameter can also be used in + conjunction with the deprecated relativeRef + parameter. See the relativeRef + section for more details.

      +

      Example: did:example:123456789abcdefghi/path/to/file.txt?service=%23files
      + Considers only the service in the resolved DID + Document with the specified id value of (percent + decoded) #files in determining how to process the + DID URL path.

      +
      + +
      +
      serviceType
      +

      Indicates that only the service entry or entries with the specified + type are to be considered when processing the path + component of a DID URL. If present, each value + MUST be an ASCII string. The service query + parameter MAY appear multiple times in a DID + URL. If no matching services are found, the dereferencing + process MUST fail.

      +

      Example: did:example:123456789abcdefghi/path/to/file.txt?serviceType=FileService
      + Considers only the service in the resolved DID + Document with the type value of FileService in determining how to process the + DID URL path.

      +
      + +
      +
      relativeRef (deprecated)
      +

      A relative URI reference to a resource at a selected service endpoint. + This parameter is deprecated and replaced by explicit + path-based dereferencing.

      +

      If present, each value + MUST be an ASCII string representing a relative + URL path that is percent-encoded as required by RFC3986. + The relativeRef query parameter + MUST be used in conjunction with a single + service query parameter. The service + query parameter is used to identify a specific + service entry in the DID Document, and the + value of the relativeRef query parameter is + percent-decoded and appended to the serviceEndpoint + of the selected service. The resulting URL is then + resolved, and if successful, the resolved resource and metadata + are returned. If there is no service parameter, or + no service is identified in the resolved DID + Document, the dereferencing process MUST + fail with an error.

      +

      Example: did:example:123456789abcdefghi&service=storage&relativeRef=invoices%2Fnov2025.pdf
      + Append "invoices/nov2025.pdf" to the serviceEndpoint of + the storage service and attempt to retrieve the + resource at that URL, returning the resulting resource and + metadata or an error.

      +
      + +
      +
      hl
      +

      The value of the parameter is a hashlink (as defined + in Hashlink). + If present, it MUST be an ASCII string representing the expected + multihash of the resource content. The DID + Resolver MUST calculate the + multihash of the dereferenced content using the steps + below and compare the result to the provided hashlink. If the + values match, proceed with returning the resource and metadata. + If the values do not match, the DID Resolver + MUST return an error.

      +

      Hash calculation steps:

      +
        +
      1. Determine from the query parameter multihash value's + prefix which hashing algorithm and encoding to use for the + calculation.
        2. +
      2. Calculate the hash of the resource content using the + same hashing algorithm and encoding.
        3. +
      3. Verify that the calculated multihash and + hl value match. If they do not match, return an + error.
        4. +
      4. If the hashes match, continue with the processing of the + resource.
        5. +
      +

      Example: did:example:123456789abcdefghi?hl=hl:zQmYw5...oTwD
      + Ensures the integrity of the resolved content by verifying that it matches the specified hashlink.

      +
      +
      -

      - This behavior of the DID fragment is analogous to the handling of a fragment in an HTTP URL in the - case when dereferencing it returns an HTTP 3xx (Redirection) response with a - Location header (see section 7.1.2 of [[RFC7231]]). -

      +
      +

      Service Types

      + +
      +
      FileService
      + +

      A FileService is a service defined in a + DID Document that includes a prefix + attribute that enables participation in the deterministic + mapping of the DID URL path component to a resolvable + resource URL as described in the DID URL + Path handling section. When a service of type + FileService is selected during that process, the + DID Resolver MUST perform the following steps to + construct resource URL and dereference that URL.

      + +
        +
      1. Remove the matching prefix value from the DID URL path.
        2. +
      2. Append the remaining path segment to the serviceEndpoint URL.
        3. +
      3. Attempt to resolve the resulting URL.
        4. +
      4. If resolution is successful, return the resulting content + and dereferencing metadata.
        5. +
      5. If resolution fails, return an appropriate error.
        6. +
      -
      +

      The prefix value MUST begin with a forward slash + (/) and MUST represent a valid path as defined by + RFC3986 Section 3.3.

      -
      +

      The serviceEndpoint value must be a valid URL as defined by + RFC3986 + and serves as the base for resources referenced by the + DID URL Path.

      -
      -

      Examples

      +

      See DID URL Path + Examples for practical usage of FileService, + including cases with overlapping prefixes, non-root mappings, + and multi-service DID Documents.

      +
      +
      +
-
-

Example: Dereferencing to verification method

-

Given the following input DID URL:

- 
-	did:example:123456789abcdefghi#keys-1
-
-

... and the following resolved DID document:

- 

-	{
-		"@context":[
-			"https://www.w3.org/ns/did/v1.1",
-			"https://didcomm.org/messaging/contexts/v2",
-			"https://identity.foundation/linked-vp/contexts/v1"
-		],
-		"id": "did:example:123456789abcdefghi",
-		"verificationMethod": [{
+	

+		
Examples

+		
This section provides illustrative examples of DID URLs and
+		their corresponding dereferencing behavior.

+		
An optional fragment identifier #fragment may
+		be appended to any of these examples to reference a specific node within
+		the returned resource. Fragment processing is performed by the client
+		and is not handled by the DID Resolver.

+		
The following is the DID document that is used in all of the
+		following examples.

+
+		
+{
+	"@context": "https://www.w3.org/ns/did/v1",
+	"id": "did:example:123456789abcdefghi",
+	"versionId": "2",
+	"versionTime": "2025-10-17T17:58:43Z",
+	"verificationMethod": [
+		{
 			"id": "did:example:123456789abcdefghi#keys-1",
 			"type": "Multikey",
 			"controller": "did:example:123456789abcdefghi",
 			"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
-		}],
-		"service": [{
-			"id": "did:example:123456789abcdefghi#messages",
-			"type": "DIDCommMessaging",
-			"serviceEndpoint": "https://example.com/messages/8377464"
-		}, {
-			"id": "did:example:123456789abcdefghi#linkedvp",
-			"type": "LinkedVerifiablePresentation",
-			"serviceEndpoint": "https://example.com/verifiable-presentation.jsonld"
-		}]
-	}
-	

-			
... then the result of the  algorithm is the following output resource:

-			
-	{
-		"@context": "https://www.w3.org/ns/did/v1.1",
-		"id": "did:example:123456789abcdefghi#keys-1",
-		"type": "Multikey",
-		"controller": "did:example:123456789abcdefghi",
-		"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
-	}
-	

-			

-				Diagram showing how a DID URL can be dereferenced to a verification method
-				

-					Dereferencing a DID URL to a verification method.
-				

-			

+		}
+	],
+	"service": [
+		{
+			"type": "FileService",
+			"serviceEndpoint": "https://example.com/",
+			"prefix": "/"
+		},
+		{
+			"type": "ExampleFileService",
+			"serviceEndpoint": "https://example.com/files/",
+			"prefix": "/example/"
+		},
+		{
+			"type": "FileService",
+			"serviceEndpoint": "https://example.com/whois.vp",
+			"prefix": "/whois"
+		}
+	]
+}
+
+ +
+

Basic DID

+

+ DID URL:
+ did:example:123456789abcdefghi +

+

+ Dereferencing result:
The full, most recent + DID Document version and DID metadata is returned. A fragment + (`#keys-1`) could be appended to direct the client to use a specific + verification method + within the DID Document after resolution +

-
-

Example: Dereferencing to service endpoint URL

-

Given the following input DID URL:

- 
-	did:example:123456789abcdefghi?service=messages&relativeRef=%2Fsome%2Fpath%3Fquery#frag
-
-

... and the same resolved DID document as in the previous section.

-

... then the result of the algorithm is the following selected service endpoint URL:

- 
-	https://example.com/messages/8377464/some/path?query#frag
-
-
- Diagram showing how a DID URL can be dereferenced to a service endpoint URL -
- Dereferencing a DID URL to a service endpoint URL. -
-
+
+

DID with versionTime Query Parameter

+

DID URL:
+ did:example:123456789abcdefghi?versionTime=2025-10-01T12:00:00Z

+

Dereferencing result:
The DID Document + as it existed at the given time is returned, if DID Document + versioning is supported by the + DID Method. If the DID Method does not support + versioning, an error is returned.

+
+ +
+

DID with Path and versionTime Query Parameter

+

DID URL:
+ did:example:123456789abcdefghi/path/to/file.txt?versionTime=2025-10-01T12:00:00Z

+

Dereferencing result:
The full, most recent + DID Document version is resolved. The path component + /resume.pdf is processed using the rules defined by + DID URL path handling, and the set of + services in the resolved + DID Document. This results in the use of the + service with "type": "FileService" and + "prefix": "/" being selected. The + FileService processing steps from the FileService + specification are followed and the resource found at: + https://example.com/path/to/file.txt + is resolved. If successful, the resolved resource and related + metadata is returned.

+
+

DID With Path with Multiple Candidate Services

+

DID URL:
+ did:example:123456789abcdefghi/example/resume.pdf

+

Dereferencing result:
The full, most recent + DID Document version and DID metadata is returned.

+

The path component /example/resume.pdf is processed + using the rules defined by DID URL path + handling, using the full set of services in the + DID Document. This results in the use of the + service with "type": "ExampleFileService" and + "prefix": "/example/" being selected. The + ExampleFileService processing steps (which, for this + example, we'll assume are the same as for FileService) + are followed and the resource found at: + https://example.com/files/resume.pdf + is resolved. If successful, the resolved resource and related + metadata is returned.

+
+ +
+

Explicit Service Type Filter

+

+ DID URL:
+ did:example:123456789abcdefghi/example/resume.pdf?service=FileService +

+

Dereferencing result:
The full, most recent + DID Document version is resolved. The path component + /resume.pdf is processed using the rules defined by + DID URL path handling, with the serviceType query parameter limiting the + service entries from the DID Document to be + considered to those with "type": "FileService". This + results in the use of the service with "type": + "FileService" and + "prefix": "/" being selected. The + FileService Service Type + processing steps are followed and the resource found at: + https://example.com/example/resume.pdf + is resolved. If successful, the resolved resource and related + metadata is returned.

+
@@ -1756,7 +2054,6 @@

Method Architectures

process. -

Based on the above considerations combined with the nature of a DID method's "Read" operation, the interaction between a DID resolver and the verifiable data registry could be considered either a verifiable read @@ -1996,9 +2293,9 @@

Client-Side Dereferencing

algorithm may be performed by different components of a Resolver Architecture.

Specifically, when a DID URL with a DID fragment is dereferenced, then - Dereferencing the Resource is done by + dereferencing the resource is done by the DID resolver, and - Dereferencing the Fragment is done by the client.

+ dereferencing the fragment is done by the client.

@@ -2008,9 +2305,9 @@

Examples

Given the DID URL did:xyz:1234#keys-1, a DID resolver could be invoked via local binding - for Dereferencing the Resource (i.e., the DID document), + for dereferencing the resource (i.e., the DID document), and the client could complete the DID URL dereferencing algorithm by - Dereferencing the Fragment (i.e., a part of the DID document).

+ dereferencing the fragment (i.e., a part of the DID document).

Examples

Given the DID URL did:xyz:1234?service=agent&relativeRef=%2Fsome%2Fpath%3Fquery#frag, a DID resolver could be invoked - for Dereferencing the Resource (i.e., a service endpoint URL), + for dereferencing the resource (i.e., a service endpoint URL), and the client could complete the DID URL dereferencing algorithm by - Dereferencing the Fragment (i.e., a service endpoint URL with a fragment).

+ dereferencing the fragment (i.e., a service endpoint URL with a fragment).

Examples

Given the DID URL did:xyz:1234#keys-1, a DID resolver could be invoked via local binding, which invokes another DID resolver via remote binding - for Dereferencing the Resource (i.e., the DID document), + for dereferencing the resource (i.e., the DID document), and the client could complete the DID URL dereferencing algorithm by - Dereferencing the Fragment (i.e., a part of the DID document).

+ dereferencing the fragment (i.e., a part of the DID document).

Versioning and versionTime are mutually exclusive.

The use of the versionId DID parameter is specific to the DID method. - Its possible values may include sequential numbers, random UUIDs, content hashes, etc..

+ Its possible values may include sequential numbers, random UUIDs, content hashes, etc..

DID document metadata MAY contain a versionId property that changes with each Update operation that is performed on a DID document.