did-components.yml

openapi: 3.0.4
info:
  title: DID API Components
  version: 0.1.0
  description: Entity schemas, enums, and path parameters for the DID API.
paths: {}
components:
  parameters:
    MethodId:
      name: methodId
      in: path
      required: true
      description: |
        Verification method identifier as represented in the DID document. May be
        the fragment (for example `key-1` or, for did:key, the multibase key) or
        the absolute DID URL. The server percent-decodes this segment, so clients
        that encode `:` and `#` will resolve correctly.
      schema:
        type: string
      example: "key-1"
    ServiceId:
      name: serviceId
      in: path
      required: true
      description: DID service identifier as represented in the DID document.
      schema:
        type: string
      example: "svc-1"
    MappingId:
      name: mappingId
      in: path
      required: true
      description: Unique identifier of the key mapping.
      schema:
        type: string
      example: "km-1"
    Did:
      name: did
      in: path
      required: true
      description: |
        The DID string, for example `did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK`
        or `did:web:enterprise.example.com`. URL-encode it when your HTTP client
        does not do so automatically; the `:` characters become `%3A` on the wire
        and the server percent-decodes the captured segment before lookup.
      schema:
        type: string
      example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
    ControllerId:
      name: controllerId
      in: path
      required: true
      description: Unique identifier of the controller resource.
      schema:
        type: string
      example: "ctrl-1"
    AkaId:
      name: akaId
      in: path
      required: true
      description: Unique identifier of the also-known-as resource.
      schema:
        type: string
      example: "aka-1"
    EquivalentId:
      name: equivalentId
      in: path
      required: true
      description: Unique identifier of the equivalent-id resource.
      schema:
        type: string
      example: "eq-1"

  schemas:
    # ── Enums ──────────────────────────────────────────────────────────
    DidRole:
      type: string
      enum:
        - MANAGED
        - EXTERNAL
      description: |
        Whether the DID is managed locally (keys held in KMS) or tracked
        as an external reference.

    # W3C DID Core §5.3-§5.7
    VerificationPurpose:
      type: string
      enum:
        - authentication
        - assertionMethod
        - keyAgreement
        - capabilityInvocation
        - capabilityDelegation
      description: |
        DID Core verification relationship purpose. Values use camelCase
        matching the W3C DID Core wire format.

    Curve:
      type: string
      description: |
        Elliptic curve identifier using the registered wire-format value.
        Casing is significant; for example, `secp256k1` is lowercase by
        standard.
      enum:
        - P-256
        - P-384
        - P-521
        - secp256k1
        - Ed25519
        - Ed448
        - X25519
        - X448
      example: P-256

    JwkUse:
      type: string
      description: Intended use of the key.
      enum:
        - sig
        - enc
      example: sig

    JwkKeyType:
      type: string
      description: Supported JSON Web Key (JWK) key type parameter.
      enum:
        - EC
        - RSA
        - OKP
      example: EC

    KeyOperations:
      type: string
      description: Specific operations the key is intended for.
      enum:
        - sign
        - verify
        - encrypt
        - decrypt
        - wrapKey
        - unwrapKey
        - deriveKey
        - deriveBits
      example: sign

    Jwk:
      type: object
      description: |
        A public JSON Web Key (JWK). This schema models the common public
        members used by the DID API and does not enforce every JOSE
        key-type-specific constraint. The example below is the Ed25519 public
        key for the canonical did:key sample; an EC P-256 key would instead
        carry `kty: EC`, `crv: P-256`, and both `x` and `y`.
      required:
        - kty
      example:
        kty: "OKP"
        crv: "Ed25519"
        x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
        use: "sig"
        alg: "EdDSA"
      properties:
        kty:
          $ref: '#/components/schemas/JwkKeyType'
        kid:
          type: string
          description: Key identifier used to uniquely identify the key.
          example: "key-12345"
        alg:
          type: string
          description: The algorithm intended for use with the key.
          example: "ES256"
        use:
          $ref: '#/components/schemas/JwkUse'
        key_ops:
          type: array
          items:
            $ref: '#/components/schemas/KeyOperations'
          description: The allowed cryptographic operations for the key.
        crv:
          $ref: '#/components/schemas/Curve'
        x:
          type: string
          description: The x coordinate for elliptic curve keys (base64url-encoded).
        y:
          type: string
          description: The y coordinate for elliptic curve keys (base64url-encoded).
        n:
          type: string
          description: The modulus value for RSA keys (base64url-encoded).
        e:
          type: string
          description: The public exponent for RSA keys (base64url-encoded).
          example: "AQAB"
        x5c:
          type: array
          items:
            type: string
          description: X.509 certificate chain as base64-encoded DER certificates.
        x5t:
          type: string
          description: X.509 certificate SHA-1 thumbprint (base64url-encoded).
        x5u:
          type: string
          format: uri
          description: URL pointing to an X.509 certificate or certificate chain.
        x5t#S256:
          type: string
          description: X.509 certificate SHA-256 thumbprint (base64url-encoded).

    # ── Entity Schemas ─────────────────────────────────────────────────
    # Aggregate root of the DID API model. Inline convenience arrays
    # carry lightweight string values for display and filtering; richer
    # objects (controllers, verification methods, services, etc.) live on
    # their dedicated sub-resource endpoints.
    #
    # Two response shapes:
    #   - `Did`        lightweight summary. Used by every endpoint that
    #                    does not accept `?expand=` (POST create, PATCH
    #                    update, PUT replace, deactivate, track external).
    #   - `DidDetail`  extends `Did` with the optional `document` and
    #                    `keys` projections. Used only by endpoints that
    #                    accept `?expand=document,keys`: currently
    #                    GET /dids and GET /dids/{did}.
    Did:
      type: object
      description: Core DID resource representing a managed or external DID.
      required:
        - did
        - method
        - role
        - createdAt
        - updatedAt
      example:
        did: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        method: "key"
        alias: "rest-e2e-alias"
        role: "MANAGED"
        alsoKnownAs: []
        equivalentIds: []
        createdAt: "2026-06-06T09:00:00Z"
        updatedAt: "2026-06-06T09:00:00Z"
      properties:
        did:
          type: string
          example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
          description: The DID string.
        method:
          type: string
          example: "key"
          description: The DID method (e.g., key, web, ion, jwk).
        alias:
          type: string
          nullable: true
          description: Optional human-readable alias for this DID.
          example: "rest-e2e-alias"
        role:
          $ref: '#/components/schemas/DidRole'
        # `deactivated` and `controllers` are DID-document state and live on
        # `DidDocument` / `DidDocumentMetadata`. Fetch the document to read
        # them; use the `includeDeactivated` filter on list endpoints.
        alsoKnownAs:
          type: array
          items:
            type: string
          description: Inline convenience view of also-known-as URIs.
          example:
            - "https://acme.example.com/about"
        # DID 1.1 / Controlled Identifiers v1.0
        equivalentIds:
          type: array
          items:
            type: string
          description: Inline convenience view of equivalent DID strings.
          example:
            - "did:web:acme.example.com"
        canonicalId:
          type: string
          nullable: true
          description: Canonical DID identifier if different from the primary DID.
          example: "did:web:enterprise.example.com"
        createdAt:
          type: string
          format: date-time
          description: Timestamp the local DID resource was created.
          example: "2026-06-06T09:00:00Z"
        updatedAt:
          type: string
          format: date-time
          description: Timestamp the local DID resource was last updated.
          example: "2026-06-06T09:00:00Z"
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: Soft-delete timestamp. Present only when the DID has been deleted.
          example: "2026-06-06T10:30:00Z"

    DidDetail:
      description: |
        `Did` plus the optional `document` and `keys` projections. Used as the
        response shape for endpoints that accept `?expand=document,keys`:
        currently GET /dids and GET /dids/{did}. Both projection fields are
        present only when the caller opted in via `?expand=`; otherwise the
        response is shape-equivalent to `Did`.
      allOf:
        - $ref: '#/components/schemas/Did'
        - type: object
          properties:
            document:
              $ref: '#/components/schemas/DidDocument'
              nullable: true
              description: |
                Resolved DID document. Present only when the request used
                `?expand=document` (or `?expand=all`). Absent on the default
                lightweight response.
            keys:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/KeyMapping'
              description: |
                Inline list of KMS key mappings for this DID's managed
                verification methods. Present only when the request used
                `?expand=keys` (or `?expand=all`). Absent on the default
                lightweight response.

    KeyInfo:
      type: object
      description: |
        Reference to a KMS-managed key. Used wherever a wire DTO
        identifies a key: request bodies (DID create, VM create,
        key-mapping create), patch bodies (VM update), and read responses
        (VM, KeyMapping). The wire shape carries metadata only; raw key
        material is never transferred via this object. For creation flows
        (DID create, VM create) the server resolves the public JWK from
        the registered KMS key referenced here, so register the
        key with the KMS first (for example via the KMS keys endpoint).

        At least one of `providerId` plus `alias` or `kid` is required for
        operations that need to resolve a key. Read responses populate
        whichever fields the key record supplied (typically
        `providerId`/`alias`/`kid` plus the optional `keyType`/
        `signatureAlgorithm`/`keyEncoding` triplet).
      example:
        providerId: "softwaretest"
        alias: "rest-e2e-alias"
        keyType: "P-256"
        signatureAlgorithm: "ES256"
        keyEncoding: "JWK"
      properties:
        providerId:
          type: string
          nullable: true
          description: KMS provider identifier.
          example: "softwaretest"
        alias:
          type: string
          nullable: true
          description: Key alias in the KMS.
          example: "rest-e2e-alias"
        kid:
          type: string
          nullable: true
          description: Key identifier.
          example: "key-12345"
        keyType:
          type: string
          nullable: true
          description: |
            Canonical key-type identifier (e.g. `Ed25519`, `Secp256k1`,
            `P-256`, `RSA-2048`). Resolved from the key record on read; null
            when the lookup record carries no `keyType`.
          example: "P-256"
        signatureAlgorithm:
          type: string
          nullable: true
          description: |
            Default signature algorithm associated with the key
            (e.g. `EdDSA`, `ES256K`, `ES256`). Resolved from the key record
            on read.
          example: "ES256"
        keyEncoding:
          type: string
          nullable: true
          description: |
            Encoding of the public key material in the key record
            (e.g. `JWK`, `Multibase`). Resolved from the key record
            on read.
          example: "JWK"

    VerificationMethod:
      type: object
      description: |
        A verification method associated with a DID. References the key
        material via KMS (`keyInfo.providerId` + `keyInfo.alias`/`keyInfo.kid`).
        For W3C-compliant key material representations, use the resolution
        endpoint.

        Both managed and external DIDs reference key material through the
        KMS: managed keys are generated in-KMS, external public keys are
        registered into the KMS first (see KMS register endpoint). The DID
        manager never holds raw key bytes.
      required:
        - id
        - type
        - controller
        - keyInfo
      example:
        id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        type: "JsonWebKey2020"
        controller: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        keyInfo:
          providerId: "softwaretest"
          alias: "rest-e2e-alias"
        referenceVerificationRelations:
          - "authentication"
          - "assertionMethod"
        ordinal: 0
      properties:
        id:
          type: string
          description: |
            Verification method identifier as represented in the DID document.
            May be a fragment (for example `#key-1`) or an absolute DID URL.
            For did:key the fragment is the multibase key itself.
          example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        type:
          type: string
          description: |
            Verification method type. Known values include: JsonWebKey2020,
            Ed25519VerificationKey2020, EcdsaSecp256k1VerificationKey2019,
            X25519KeyAgreementKey2020, Multikey.
          example: "JsonWebKey2020"
        controller:
          type: string
          description: DID of the controller of this verification method.
          example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: |
            Expiration timestamp of the verification method (DID 1.1 / CID).
            When present and in the past, the VM is no longer considered valid.
        revokedAt:
          type: string
          format: date-time
          nullable: true
          description: |
            Revocation timestamp of the verification method (DID 1.1 / CID).
            Distinct from key revocation in the KMS: a VM may be revoked
            within a DID document while the underlying KMS key remains usable
            for other purposes, and vice versa.
        valueVerificationRelation:
          allOf:
            - $ref: '#/components/schemas/VerificationPurpose'
          nullable: true
          description: |
            If set, this verification method is embedded BY VALUE inside
            this single verification relationship in the DID document
            (e.g., embedded directly in `assertionMethod`). Per W3C
            semantics a VM may be embedded by value in at most one
            relationship; use `referenceVerificationRelations` for any
            additional relationships. When null, the VM lives in the
            top-level `verificationMethod` array of the DID document.
          example: "authentication"
        referenceVerificationRelations:
          type: array
          items:
            $ref: '#/components/schemas/VerificationPurpose'
          description: |
            Verification relationships that REFERENCE this VM by DID URL.
            The VM itself is rendered either in the top-level
            `verificationMethod` array (when `valueVerificationRelation`
            is null) or embedded by value inside the
            `valueVerificationRelation` purpose; entries listed here
            point to it via DID URL from their respective purpose arrays.
          example:
            - "authentication"
            - "assertionMethod"
        extensionProperties:
          type: object
          additionalProperties: true
          nullable: true
          description: |
            Bag of unknown/extension properties carried by the verification
            method in the original DID document, preserved for lossless
            round-tripping (DID 1.1 extensibility).
        ordinal:
          type: integer
          description: Ordering position within the DID document.
          example: 0

    VerificationRelationshipView:
      type: object
      description: |
        Read-only per-purpose view of a verification relationship, derived
        from the verification methods of the DID. The source of truth is
        each `VerificationMethod`'s `valueVerificationRelation` (at most
        one VM may be embedded by value per purpose) and
        `referenceVerificationRelations`. To add or remove a VM from a
        relationship, update the VM directly.
      required:
        - purpose
        - referenceVerificationMethodIds
      example:
        purpose: "authentication"
        embeddedVerificationMethodId: null
        referenceVerificationMethodIds:
          - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
      properties:
        purpose:
          $ref: '#/components/schemas/VerificationPurpose'
        embeddedVerificationMethodId:
          type: string
          nullable: true
          description: |
            Identifier of the verification method embedded BY VALUE in
            this relationship (the VM whose `valueVerificationRelation`
            equals this purpose). Null if no VM is embedded by value.
          example: null
        referenceVerificationMethodIds:
          type: array
          items:
            type: string
          description: |
            Identifiers of verification methods referenced from this
            relationship by DID URL (i.e., VMs that list this purpose in
            their `referenceVerificationRelations`). The referenced VMs
            live either in the top-level `verificationMethod` array or
            are embedded by value in another relationship.
          example:
            - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"

    KeyMapping:
      type: object
      description: |
        Binds a DID verification method to a KMS-managed key reference.
      required:
        - id
        - verificationMethod
        - keyInfo
        - purposes
      example:
        id: "km-1"
        verificationMethod: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        keyInfo:
          providerId: "softwaretest"
          alias: "rest-e2e-alias"
        purposes:
          - "authentication"
          - "assertionMethod"
      properties:
        id:
          type: string
          description: Unique identifier of the key-mapping resource.
          example: "km-1"
        verificationMethod:
          type: string
          description: Verification method identifier this key reference belongs to.
          example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        purposes:
          type: array
          items:
            $ref: '#/components/schemas/VerificationPurpose'
          description: Verification purposes this key mapping serves.
          example:
            - "authentication"
            - "assertionMethod"

    # W3C DID Core §5.1.2
    Controller:
      type: object
      description: A controller resource for a DID.
      required:
        - id
        - controllerDid
      example:
        id: "ctrl-1"
        controllerDid: "did:web:controller-a.example.com"
        ordinal: 0
      properties:
        id:
          type: string
          description: Unique identifier of the controller resource.
          example: "ctrl-1"
        controllerDid:
          type: string
          description: The controller DID string.
          example: "did:web:controller-a.example.com"
        ordinal:
          type: integer
          description: Ordering position.
          example: 0

    # W3C DID Core §5.1.1
    AlsoKnownAsEntry:
      type: object
      description: An also-known-as URI resource for a DID.
      required:
        - id
        - akaUri
      example:
        id: "aka-1"
        akaUri: "https://acme.example.com/about"
        ordinal: 0
      properties:
        id:
          type: string
          description: Unique identifier of the also-known-as resource.
          example: "aka-1"
        akaUri:
          type: string
          description: The also-known-as URI.
          example: "https://acme.example.com/about"
        ordinal:
          type: integer
          description: Ordering position.
          example: 0

    # DID 1.1 / Controlled Identifiers v1.0
    EquivalentIdEntry:
      type: object
      description: An equivalent-id resource for a DID.
      required:
        - id
        - equivalentDid
      example:
        id: "eq-1"
        equivalentDid: "did:web:acme.example.com"
        ordinal: 0
      properties:
        id:
          type: string
          description: Unique identifier of the equivalent-id resource.
          example: "eq-1"
        equivalentDid:
          type: string
          description: The equivalent DID string.
          example: "did:web:acme.example.com"
        ordinal:
          type: integer
          description: Ordering position.
          example: 0

    # ── DIF-compatible resolution schemas ──────────────────────────
    # W3C DID Resolution + DIF Universal Resolver
    DidDocumentContext:
      description: DID document JSON or JSON-LD context value.
      oneOf:
        - type: string
        - type: array
          items:
            oneOf:
              - type: string
              - type: object
                additionalProperties: true

    DidDocumentController:
      description: DID document controller value.
      oneOf:
        - type: string
        - type: array
          items:
            type: string

    DidDocumentVerificationMethod:
      type: object
      description: |
        Verification method as represented in a DID document, limited to the
        verification material forms supported by this API.
      oneOf:
        - required: [publicKeyJwk]
        - required: [publicKeyMultibase]
        - required: [blockchainAccountId]
      required:
        - id
        - type
        - controller
      example:
        id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        type: "JsonWebKey2020"
        controller: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        publicKeyMultibase: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        publicKeyJwk:
          kty: "OKP"
          crv: "Ed25519"
          x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
      properties:
        id:
          type: string
          description: Verification method identifier in DID document form.
          example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        type:
          type: string
          description: Verification method type.
          example: "JsonWebKey2020"
        controller:
          type: string
          description: DID of the controller of this verification method.
          example: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        publicKeyJwk:
          $ref: '#/components/schemas/Jwk'
        publicKeyMultibase:
          type: string
          description: Multibase-encoded public key.
          example: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        blockchainAccountId:
          type: string
          description: CAIP-10 blockchain account identifier.
          example: "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb"
      additionalProperties: true

    DidDocumentVerificationMethodReference:
      description: DID document verification relationship entry.
      oneOf:
        - type: string
          description: DID URL reference to an existing verification method.
        - $ref: '#/components/schemas/DidDocumentVerificationMethod'

    DidDocumentService:
      type: object
      description: |
        A service endpoint of a DID, represented as it appears in the
        DID document `service` array. The `type` field matches DID Core
        wire format (singular `type`, not `types`). Used both as the W3C
        wire shape and as the public API resource for service CRUD.
      required:
        - id
        - type
        - serviceEndpoint
      example:
        id: "svc-1"
        type: "LinkedDomains"
        serviceEndpoint: "https://example.com/service"
      properties:
        id:
          type: string
          description: |
            Service identifier as represented in the DID document. May be a
            fragment or an absolute DID URL.
          example: "svc-1"
        type:
          description: |
            Service type. DID Core uses `type` (not `types`). May be a single
            string or an array of strings per the W3C specification.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: "LinkedDomains"
        serviceEndpoint:
          description: |
            Service endpoint. Polymorphic per W3C DID Core: may be a URI string,
            an object, or an array of URIs/objects.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
            - type: array
              items:
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties: true
          example: "https://example.com/service"
      additionalProperties: true

    DidDocument:
      type: object
      description: |
        W3C DID document representation. The example below is the document
        resolved for a did:key (Ed25519): the public key appears both as a JWK
        and as a multibase string, the authentication, assertionMethod,
        capabilityInvocation, and capabilityDelegation relationships reference
        the primary key by DID URL, and a derived X25519 key serves keyAgreement.
      required:
        - id
      example:
        id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        verificationMethod:
          - id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
            type: "JsonWebKey2020"
            controller: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
            publicKeyMultibase: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
            publicKeyJwk:
              kty: "OKP"
              crv: "Ed25519"
              x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
        authentication:
          - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        assertionMethod:
          - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        capabilityInvocation:
          - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        capabilityDelegation:
          - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
      properties:
        '@context':
          $ref: '#/components/schemas/DidDocumentContext'
        id:
          type: string
          description: DID subject identifier.
        controller:
          $ref: '#/components/schemas/DidDocumentController'
        alsoKnownAs:
          type: array
          items:
            type: string
          description: Alternative URIs for the DID subject.
        verificationMethod:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentVerificationMethod'
        authentication:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentVerificationMethodReference'
        assertionMethod:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentVerificationMethodReference'
        keyAgreement:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentVerificationMethodReference'
        capabilityInvocation:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentVerificationMethodReference'
        capabilityDelegation:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentVerificationMethodReference'
        service:
          type: array
          items:
            $ref: '#/components/schemas/DidDocumentService'
      additionalProperties: true

    ResolutionResult:
      type: object
      description: |
        DID resolution result. Contains the DID document alongside
        resolution and document metadata. When resolution is unsuccessful,
        `didDocument` may be `null`.
      required:
        - didDocument
        - didResolutionMetadata
        - didDocumentMetadata
      example:
        didDocument:
          id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
          verificationMethod:
            - id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
              type: "JsonWebKey2020"
              controller: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
              publicKeyMultibase: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
          authentication:
            - "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        didResolutionMetadata:
          contentType: "application/did+ld+json"
        didDocumentMetadata:
          deactivated: false
      properties:
        didDocument:
          allOf:
            - $ref: '#/components/schemas/DidDocument'
          nullable: true
        didResolutionMetadata:
          $ref: '#/components/schemas/DidResolutionMetadata'
        didDocumentMetadata:
          $ref: '#/components/schemas/DidDocumentMetadata'

    DidResolutionMetadata:
      type: object
      description: Metadata about the DID resolution process.
      example:
        contentType: "application/did+ld+json"
      properties:
        contentType:
          type: string
          description: Media type of the DID document (e.g., application/did+ld+json).
          example: "application/did+ld+json"
        error:
          $ref: '#/components/schemas/ResolutionError'
      additionalProperties: true

    # W3C DID Resolution §4.1
    DidDocumentMetadata:
      type: object
      description: Metadata about the DID document.
      example:
        created: "2026-06-06T09:00:00Z"
        updated: "2026-06-06T09:00:00Z"
        deactivated: false
      properties:
        created:
          type: string
          format: date-time
          description: When the DID was created.
          example: "2026-06-06T09:00:00Z"
        updated:
          type: string
          format: date-time
          description: When the DID document was last updated.
          example: "2026-06-06T09:00:00Z"
        deactivated:
          type: boolean
          description: Whether the DID has been deactivated.
          example: false
        nextUpdate:
          type: string
          format: date-time
          description: Expected next update time.
        versionId:
          type: string
          description: Current version identifier.
          example: "1"
        nextVersionId:
          type: string
          description: Next version identifier.
        equivalentId:
          type: array
          items:
            type: string
          description: Alternative identifiers for the same DID.
          example:
            - "did:web:acme.example.com"
        canonicalId:
          type: string
          description: Primary canonical identifier.
          example: "did:web:enterprise.example.com"
      additionalProperties: true

    DereferencingResult:
      type: object
      description: |
        DID URL dereferencing result using the HTTP binding-style `content`
        wrapper. The dereferenced content may be a DID document, a DID
        document fragment, a URI list, another representation-specific
        value, or `null` when dereferencing is unsuccessful.
      required:
        - content
        - dereferencingMetadata
        - contentMetadata
      example:
        content:
          id: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
          type: "JsonWebKey2020"
          controller: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
          publicKeyMultibase: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
        dereferencingMetadata:
          contentType: "application/did+ld+json"
        contentMetadata: {}
      properties:
        content:
          nullable: true
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items:
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties: true
            - type: string
          description: |
            The dereferenced resource. May be a DID document, verification
            method, service endpoint, URI list, or other representation-
            specific value.
        dereferencingMetadata:
          $ref: '#/components/schemas/DereferencingMetadata'
        contentMetadata:
          type: object
          additionalProperties: true
          description: Metadata about the dereferenced content.

    DereferencingMetadata:
      type: object
      description: Metadata about the DID URL dereferencing process.
      example:
        contentType: "application/did+ld+json"
      properties:
        contentType:
          type: string
          description: Media type of the dereferenced content.
          example: "application/did+ld+json"
        error:
          $ref: '#/components/schemas/ResolutionError'
      additionalProperties: true

    ResolutionError:
      type: string
      description: |
        DID resolution or dereferencing error code, returned inside
        `didResolutionMetadata.error` / `dereferencingMetadata.error`. `notFound`
        is the most common value for an unknown DID.
      enum:
        - invalidDid
        - invalidDidUrl
        - notFound
        - representationNotSupported
        - methodNotSupported
        - invalidPublicKey
        - invalidPublicKeyLength
        - invalidPublicKeyType
        - internalError
      example: "notFound"

    DidMethodCapabilities:
      type: object
      description: |
        Full capabilities snapshot for one DID method. The example below is the
        registered profile for did:web: fully mutable lifecycle, key and service
        management enabled, JWK and Multikey representations, 5-minute resolution
        caching, and organizational usage guidance. did:key and did:jwk instead
        report an immutable lifecycle with key and service management disabled.
      required: [method]
      example:
        method: "web"
        lifecycle:
          create: true
          update: true
          deactivate: true
          delete: true
        keyManagement:
          addition: true
          replacement: true
          removal: true
          supportedKeyTypes:
            - keyType: "OKP"
              curve: "Ed25519"
              algorithm: "Ed25519"
            - keyType: "EC"
              curve: "secp256k1"
              algorithm: "ES256K"
            - keyType: "EC"
              curve: "P-256"
              algorithm: "ES256"
            - keyType: "EC"
              curve: "P-384"
              algorithm: "ES384"
        serviceManagement:
          addition: true
          replacement: true
          removal: true
        representations:
          jsonWebKey2020: true
          multikey: true
          ed25519VerificationKey2020: false
          ed25519VerificationKey2018: false
          ecdsaSecp256k1VerificationKey2019: false
        resolution:
          allowsCaching: true
          allowsLocalRecord: true
          cacheTtlSeconds: 300
        recommendations:
          naturalPersons: false
          organizations: true
          ephemeral: false
          longLived: true
        metadata:
          description: "DID method using web domain verification"
          specificationUrl: "https://w3c-ccg.github.io/did-method-web/"
      properties:
        method:
          type: string
          description: The DID method name this capability snapshot describes.
          example: "web"
        lifecycle:
          type: object
          description: |
            Lifecycle operation flags: `create`, `update`, `deactivate`,
            `delete`. did:key and did:jwk have only `create` true.
        keyManagement:
          type: object
          description: |
            Key management flags (`addition`, `replacement`, `removal`) plus
            `supportedKeyTypes`, a list of `{keyType, curve, algorithm}` entries.
        serviceManagement:
          type: object
          description: Service management flags (`addition`, `replacement`, `removal`).
        representations:
          type: object
          description: |
            Supported verification method representation formats
            (jsonWebKey2020, multikey, ed25519VerificationKey2020/2018,
            ecdsaSecp256k1VerificationKey2019).
        resolution:
          type: object
          description: |
            Resolution and caching behaviour: `allowsCaching`,
            `allowsLocalRecord`, `cacheTtlSeconds`.
        recommendations:
          type: object
          description: |
            Usage guidance flags (not enforcement): `naturalPersons`,
            `organizations`, `ephemeral`, `longLived`.
        metadata:
          type: object
          description: "Descriptive metadata: `description`, `specificationUrl`, `version`."
      additionalProperties: true