openapi: 3.1.0
servers:
  - url: "/1.0/"
info:
  title: DID Resolution and DID URL Dereferencing
  description: DID Resolution and DID URL Dereferencing
  version: 1.0.0
  contact:
    name: W3C Decentralized Identifier Working Group
    url: https://www.w3.org/groups/wg/did/
paths:
  "/identifiers/{identifier}":
    get:
      summary: Resolve a DID / Dereference a DID URL
      description: <p>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.</p>
        <p>See the <a href="<a href="https://www.w3.org/TR/did-resolution/">DID
        Resolution</a> specification for additional details.</p>
      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.
        - in: query
          name: options
          schema:
            oneOf:
              - $ref: "#/components/schemas/ResolutionOptions"
              - $ref: "#/components/schemas/DereferencingOptions"
          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: <p>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.</p>
        <p>See the <a href="<a href="https://www.w3.org/TR/did-resolution/">DID
        Resolution</a> specification for additional details.</p>
      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!
          content:
            application/did:
              schema:
                type: object
                description: The DID document.
                example:
                  "@context": https://www.w3.org/ns/did/v1.1
                  id: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw
                  verificationMethod:
                    - id: did:indy:sovrin:WRfXPg8dantKVubE3HX8pw#key-1
                      type: Ed25519VerificationKey2018
                      publicKeyBase58: H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
        "400":
          description: Invalid DID or DID URL.
          content:
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
        "404":
          description: DID or DID URL not found.
          content:
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
        "406":
          description: Representation not supported.
          content:
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
        "410":
          description: Successfully resolved, but DID is deactivated.
          content:
            application/did:
              schema:
                type: object
                description: The deactivated DID document.
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
        "500":
          description: Internal Error.
          content:
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
        "501":
          description: DID method not supported.
          content:
            application/did-resolution:
              schema:
                $ref: "#/components/schemas/ResolutionResult"
            application/did-url-dereferencing:
              schema:
                $ref: "#/components/schemas/DereferencingResult"
components:
  schemas:
    ResolutionOptions:
      description: The DID resolution options. See https://www.w3.org/TR/did-resolution/#did-resolution-options
      type: object
      properties:
        expandRelativeUrls:
          type: boolean
        versionId:
          type: string
        versionTime:
          type: string
          format: date-time
      additionalProperties: { }
    DereferencingOptions:
      description: The DID URL dereferencing options. See https://www.w3.org/TR/did-resolution/#did-url-dereferencing-options
      type: object
      properties:
        verificationRelationship:
          type: string
      additionalProperties: { }
    ResolutionResult:
      description: The DID resolution result.
      type: object
      properties:
        didDocument:
          type: object
        didResolutionMetadata:
          $ref: "#/components/schemas/DidResolutionMetadata"
        didDocumentMetadata:
          $ref: "#/components/schemas/DidDocumentMetadata"
    DidResolutionMetadata:
      type: object
      properties:
        contentType:
          type: string
        error:
          $ref: "#/components/schemas/RFC9457ProblemDetails"
      additionalProperties: { }
    DidDocumentMetadata:
      type: object
      properties:
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        deactivated:
          type: string
        nextUpdate:
          type: string
          format: date-time
        versionId:
          type: string
        nextVersionId:
          type: string
        equivalentId:
          type: array
          items:
            type: string
        canonicalId:
          type: string
      additionalProperties: { }
    DereferencingResult:
      description: The DID URL dereferencing result.
      type: object
      properties:
        content:
          type: object
        dereferencingMetadata:
          $ref: "#/components/schemas/DereferencingMetadata"
        contentMetadata:
          $ref: "#/components/schemas/ContentMetadata"
    DereferencingMetadata:
      type: object
      properties:
        contentType:
          type: string
        error:
          $ref: "#/components/schemas/RFC9457ProblemDetails"
      additionalProperties: { }
    ContentMetadata:
      type: object
      additionalProperties: { }
    RFC9457ProblemDetails:
      type: object
      required:
        - type
        - title
      properties:
        type:
          type: string
        status:
          type: integer
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
      additionalProperties: { }