From ce5179692ef7c419e794115204db0bf8f0dc1a1d Mon Sep 17 00:00:00 2001 From: Markus Sabadello Date: Thu, 18 Sep 2025 14:51:50 +0200 Subject: [PATCH 1/2] Define HTTP POST binding in addition to HTTP GET --- index.html | 73 +++++++++++++++++++++++++++++++------------- openapi/openapi.yaml | 58 +++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 22 deletions(-) diff --git a/index.html b/index.html index 828a9f1..10a0131 100644 --- a/index.html +++ b/index.html @@ -2221,16 +2221,8 @@

HTTP(S) Binding

https://resolver.example/1.0/identifiers/did:example:1234
  • Set the Accept HTTP request header to `application/did-resolution"` in order to request a complete , OR
    • -
  • set the Accept HTTP request header to the value of the accept resolution option.
    • -
  • If any other resolution options are provided: -
      -
    1. The input DID MUST be URL-encoded (as specified in RFC3986 Section 2.1).
      2. -
    2. Encode all resolution options except accept as - query parameters in the request HTTP(S) URL. - 
      https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2
      3. -
    -
    • +
  • set the Accept HTTP request header to the value of the accept resolution option + in order to request only the didDocument value of the result.
  • For the DID URL dereferencing function: @@ -2239,20 +2231,57 @@

    HTTP(S) Binding

    https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf
  • Set the Accept HTTP request header to `application/did-url-dereferencing"` in order to request a complete , OR
    • -
  • set the Accept HTTP request header to the value of the accept dereferencing option.
    • -
  • If any other dereferencing options are provided: -
      -
    1. The input DID URL MUST be URL-encoded (as specified in RFC3986 Section 2.1).
      2. -
    2. Encode all dereferencing options except accept as - query parameters in the request HTTP(S) URL. - 
      https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2
      3. -
    -
    • +
  • set the Accept HTTP request header to the value of the accept dereferencing option + in order to request only the contentStream value of the result.
    • -
  • Execute an HTTP GET request on the request HTTP(S) URL. This invokes the DID resolution or - DID URL dereferencing function at the remote DID resolver.
    • +
  • For the HTTP(S) GET binding: +
      +
    1. If any other resolution options or dereferencing options than accept are provided: +
        +
      1. The input DID MUST be URL-encoded (as specified in RFC3986 Section 2.1).
        2. +
      2. Encode all resolution options except accept as + query parameters in the request HTTP(S) URL. +
      +
      2. +
    2. Execute an HTTP GET request on the request HTTP(S) URL. This invokes the DID resolution or + DID URL dereferencing function at the remote DID resolver. + 
      GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2 HTTP/1.1
+Accept: application/did-resolution
+
      + 
      GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2 HTTP/1.1
+Accept: application/did-url-dereferencing
+
      +
      3. +
    +
    • +
  • For the HTTP(S) POST binding: +
      +
    1. If any other resolution options or dereferencing options than accept are provided: +
        +
      1. Encode all resolution options except accept as + a JSON structure in the HTTP request's POST body. +
      +
      2. +
    2. Execute an HTTP POST request on the request HTTP(S) URL. This invokes the DID resolution or + DID URL dereferencing function at the remote DID resolver. + 
      POST https://resolver.example/1.0/identifiers/did:example:1234 HTTP/1.1
+Accept: application/did-resolution
+
+{
+    "option1": "value1",
+    "option2": "value2"
+}
      + 
      POST https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf HTTP/1.1
+Accept: application/did-url-dereferencing
+
+{
+    "option1": "value1",
+    "option2": "value2"
+}
      +
    +
  • If the DID resolution or DID URL dereferencing function returns an error metadata property in the didResolutionMetadata or dereferencingMetadata, then the HTTP response status code MUST correspond to the value of the error metadata property, diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index fcf805e..51b17ab 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -68,6 +68,64 @@ paths: description: The options for resolving the DID or dereferencing the DID URL. style: form explode: true + post: + summary: Resolve a DID / Dereference a DID URL + description:

    This endpoint either resolves a DID, or dereferences a DID URL. + When resolving a DID, + it takes the DID and resolution options as inputs, and + the output is a DID document plus metadata. + When dereferencing a DID URL, + it takes the DID URL and dereferencing options as inputs, and + the output is a DID document, a part of a DID document, or some + other resource identified by the DID URL.

    +

    See the DID + Resolution specification for additional details.

    + operationId: resolve + tags: + - Universal Resolver + parameters: + - in: path + required: true + name: identifier + schema: + type: string + description: The DID to be resolved, or the DID URL to be dereferenced. + examples: + example1: + value: did:indy:sovrin:builder:VbPQNHsvoLZdaNU7fTBeFx + description: A DID using the `indy` method. + example2: + value: did:ion:EiClkZMDxPKqC9c-umQfTkR8vvZ9JPhl_xLDI9Nfk38w5w + description: A DID using the `ion` method. + example3: + value: did:ebsi:z25ZZFS7FweHsm9MX2Qvc6gc + description: A DID using the `ebsi` method. + - in: header + required: false + name: Accept + schema: + type: string + description: The requested media type of the DID document representation or + DID resolution result. + examples: + application/did: + value: application/did + description: Media type of a DID document. + application/did-resolution: + value: application/did-resolution + description: Media type of a DID resolution result. + application/did-url-dereferencing: + value: application/did-url-dereferencing + description: Media type of a DID URL dereferencing result. + requestBody: + content: + application/did-resolution: + schema: + $ref: "#/components/schemas/ResolutionOptions" + application/did-url-dereferencing: + schema: + $ref: "#/components/schemas/DereferencingOptions" + description: The options for resolving the DID or dereferencing the DID URL. responses: "200": description: successfully resolved! From 72eaf12bf29dd11593e362d5de74e4be2e08e4fe Mon Sep 17 00:00:00 2001 From: Markus Sabadello Date: Wed, 24 Sep 2025 09:31:13 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr --- index.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 10a0131..b93d005 100644 --- a/index.html +++ b/index.html @@ -2220,9 +2220,9 @@

    HTTP(S) Binding

  • Append the input DID to the request HTTP(S) URL. 
    https://resolver.example/1.0/identifiers/did:example:1234
  • Set the Accept HTTP request header to `application/did-resolution"` - in order to request a complete , OR
    • + to request a complete , OR
  • set the Accept HTTP request header to the value of the accept resolution option - in order to request only the didDocument value of the result.
    • + to request only the didDocument value of the result.
  • For the DID URL dereferencing function: @@ -2230,9 +2230,9 @@

    HTTP(S) Binding

  • Append the input DID URL to the request HTTP(S) URL. 
    https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf
  • Set the Accept HTTP request header to `application/did-url-dereferencing"` - in order to request a complete , OR
    • + to request a complete , OR
  • set the Accept HTTP request header to the value of the accept dereferencing option - in order to request only the contentStream value of the result.
    • + to request only the contentStream value of the result.
  • For the HTTP(S) GET binding: