openapi: "3.0.0"
components:
  schemas:
# VC
    VerifiableCredential:
      type: object
      description: A credential according to the W3C and Nuts specs.
      required:
        - "@context"
        - type
        - issuer
        - issuanceDate
        - credentialSubject
        - proof
      properties:
        "@context":
          description: "List of URIs of JSON-LD contexts of the VC."
        id:
          description: Credential ID. An URI which uniquely identifies the credential e.g. the issuers DID concatenated with a UUID.
          example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic#b53bda82-712a-4d20-b673-e67efaf60acc
          type: string
        type:
          description: A single string or array of strings. The value(s) indicate the type of credential. It should contain `VerifiableCredential`. Each type should be defined in the @context.
          type: array
          items:
            type: string
        issuer:
          $ref: '#/components/schemas/DID'
        issuanceDate:
          description: rfc3339 time string when the credential was issued.
          type: string
          example: "2012-01-02T12:00:00Z"
        expirationDate:
          description: rfc3339 time string until when the credential is valid.
          type: string
          example: "2012-01-02T12:00:00Z"
        credentialSubject:
          $ref: '#/components/schemas/CredentialSubject'
        proof:
          description: one or multiple cryptographic proofs

    CredentialSubject:
      description: Subject of a Verifiable Credential identifying the holder and expressing claims.

    Revocation:
      type: object
      description: Credential revocation record
      required:
        - issuer
        - subject
        - date
      properties:
        issuer:
          $ref: '#/components/schemas/DID'
        subject:
          type: string
          description: subject refers to the credential identifier that is revoked (not the credential subject)
        reason:
          type: string
          description: reason describes why the VC has been revoked
        date:
          type: string
          description: date is a rfc3339 formatted datetime.
        proof:
          type: object
          description: Proof contains the cryptographic proof(s).

# VP
    VerifiablePresentation:
      type: object
      description: Verifiable Presentation
      title: Verifiable Presentation Model
      required:
        - "@context"
        - type
      properties:
        "@context":
          description: |
            An ordered set where the first item is a URI https://www.w3.org/2018/credentials/v1. It is used to define
            terms and help to express specific identifiers in a compact manner.
          uniqueItems: true
          example: [
            "https://www.w3.org/2018/credentials/v1"
          ]
        id:
          type: string
          description: URI that is used to unambiguously refer to an object, such as a person, product, or organization.
          example: https://example.edu/credentials/1872,
          format: uri
        type:
          description: A single string or array of strings. Values indicate the type of object. It should contain `VerifiablePresentation`. Each type must be defined in the @context.
          example: "VerifiablePresentation"
        verifiableCredential:
          description: |
            VerifiableCredential is composed of a list containing one or more verifiable credentials, in a
            cryptographically verifiable format.
          example:
            $ref: '#/components/schemas/VerifiableCredential'
        holder:
          type: string
          description: "URI of the entity that is generating the presentation."
          format: uri
          example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic
        proof:
          description: |
            Cryptographic proofs that can be used to detect tampering and verify the authorship of a
            credential or presentation. An embedded proof is a mechanism where the proof is included in
            the data, such as a Linked Data Signature.
          example:
            $ref: "#/components/schemas/EmbeddedProof"

    EmbeddedProof:
      title: Embedded Proof
      type: object
      description: |
        Cryptographic proofs that can be used to detect tampering and verify the authorship of a
        credential or presentation. An embedded proof is a mechanism where the proof is included in
        the data, such as a Linked Data Signature.
      required:
        - type
        - created
        - proofPurpose
        - verificationMethod
        - jws
      properties:
        type:
          type: string
          description: Type of the object or the datatype of the typed value. Currently only supported value is "JsonWebSignature2020".
          example: JsonWebSignature2020.
        created:
          type: string
          description: Date and time at which proof has been created.
          example: '2021-12-20T09:00:00Z'
        proofPurpose:
          type: string
          description: |
            It expresses the purpose of the proof and ensures the information is protected by the
            signature.
          example: assertionMethod
        challenge:
          type: string
          description: |
            A random or pseudo-random value, provided by the verifier, used by some authentication protocols to
            mitigate replay attacks.
        domain:
          type: string
          description: |
            A string value that specifies the operational domain of a digital proof. This could be an Internet domain
            name like example.com, an ad-hoc value such as mycorp-level3-access, or a very specific transaction value
            like 8zF6T$mqP. A signer could include a domain in its digital proof to restrict its use to particular
            target, identified by the specified domain.
        nonce:
          type: string
          description: |
            A unique string value generated by the holder, MUST only be used once for a particular domain
            and window of time. This value can be used to mitigate replay attacks.
        verificationMethod:
          type: string
          description: |
            Specifies the public key that can be used to verify the digital signature.
            Dereferencing a public key URL reveals information about the controller of the key,
            which can be checked against the issuer of the credential.
          example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic#zx1alkbvj2mqxi55WSVYWv_rek0uNO2iTZaqTTULpCE
        jws:
          type: string
          description: JSON Web Signature
          example: eyJhbGciOiJFUzI1NksifQ.eyJzdWIiOiJFQlNJIDIwMTkifQ.oggE3ft3kJYPGGa9eBibpbjgeJXw4fLbVMouVoM2NfcDxsl_UUUIarsS1VpBoYEs7s9cBlc4uC0EbnJCHfVJIw

# DID
    DID:
      type: string
      description: DID according to Nuts specification
      example: "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY"

    DIDDocument:
      type: object
      description: A DID document according to the W3C spec following the Nuts Method rules as defined in [Nuts RFC006]
      required:
        - id
        - '@context'
      properties:
        '@context':
          description: The JSON-LD contexts that define the types used in this document. Can be a single string, or a list of strings.
        controller:
          description: Single DID (as string) or List of DIDs that have control over the DID document
        id:
          $ref: '#/components/schemas/DID'
        keyAgreement:
          description: List of KIDs that can be used for encryption
          type: array
          items:
            type: string
        service:
          description: List of supported services by the DID subject
          type: array
          items:
            $ref: '#/components/schemas/Service'
        verificationMethod:
          description: list of keys
          type: array
          items:
            $ref: '#/components/schemas/VerificationMethod'
        assertionMethod:
          description: List of KIDs that may sign JWTs, JWSs and VCs
          type: array
          items:
            type: string
        authentication:
          description: List of KIDs that may alter DID documents that they control
          type: array
          items:
            type: string
        capabilityDelegation:
          description: List of KIDs that can be used to delegate capabilities that can be invoked using the DID document.
          type: array
          items:
            type: string
        capabilityInvocation:
          description: List of KIDs that can be used for signing
          type: array
          items:
            type: string

    DIDDocumentMetadata:
      type: object
      description: The DID document metadata.
      required:
        - created
        - hash
        - deactivated
        - txs
      properties:
        created:
          description: Time when DID document was created in rfc3339 form.
          type: string
        updated:
          description: Time when DID document was updated in rfc3339 form.
          type: string
        hash:
          description: Sha256 in hex form of the DID document contents.
          type: string
        previousHash:
          description: Sha256 in hex form of the previous version of this DID document.
          type: string
        txs:
          description: |
            txs lists the transaction(s) that created the current version of this DID Document.
            If multiple transactions are listed, the DID Document is conflicted
          type: array
          items:
            type: string
            description: Sha256 in hex form of the transaction
            example: "24af55bd08bfe42c603b87565c31ae8f2770e820c4b32e1e928244775ab3ed19"
        deactivated:
          description: Whether the DID document has been deactivated.
          type: boolean

    VerificationMethod:
      description: A public key in JWK form.
      required:
        - id
        - type
        - controller
        - publicKeyJwk
      properties:
        controller:
          description: The DID subject this key belongs to.
          example: did:nuts:EwVMYK2ugaMvRHUbGFBhuyF423JuNQbtpes35eHhkQic
          type: string
        id:
          description: The ID of the key, used as KID in various JWX technologies.
          type: string
        publicKeyJwk:
          description: The public key formatted according rfc7517.
          type: object
        type:
          description: The type of the key.
          example: "JsonWebKey2020"
          type: string

    Service:  # TODO: same as Endpoint in didman...
      type: object
      description: A service supported by a DID subject.
      required:
        - id
        - type
        - serviceEndpoint
      properties:
        id:
          description: ID of the service.
          type: string
        type:
          description: The type of the endpoint.
          type: string
        serviceEndpoint:
          description: Either a URI or a complex object.