fc_openapi.yaml

openapi: 3.0.1
info:
  title: Eclipse XFSC Federated Catalogue
  description: REST API of the XFSC catalogue
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://fc-server.xfsc.org
    description: some future test environment
components:
  schemas:
    AdminHealthStatus:
      type: object
      properties:
        catalogueStatus:
          type: string
          description: Catalogue service status (UP/DOWN)
        graphDbStatus:
          type: object
          properties:
            connected:
              type: boolean
            backend:
              type: string
            claimCount:
              type: integer
              format: int64
        keycloakStatus:
          type: string
          description: Keycloak status (UP/DOWN/UNKNOWN)
        fileStoreStatus:
          type: string
          description: File store status (UP/DOWN)
        databaseStatus:
          type: string
          description: Database status (UP/DOWN)
        keycloakUrl:
          type: string
          description: Keycloak issuer URL
        fileStorePath:
          type: string
          description: File store directory path
    AdminStats:
      type: object
      properties:
        totalAssets:
          type: integer
          format: int64
          description: Total number of assets in the catalogue
        activeAssets:
          type: integer
          format: int64
          description: Number of active assets
        activeTrustFrameworks:
          type: integer
          format: int64
          description: Number of active trust frameworks
        totalUsers:
          type: integer
          format: int64
          description: Total number of registered users
        totalSchemas:
          type: integer
          format: int64
          description: Total number of schemas
        totalParticipants:
          type: integer
          format: int64
          description: Total number of participants
        graphClaimCount:
          type: integer
          format: int64
          description: Number of claims in the graph database
        graphBackend:
          type: string
          description: The graph database backend type
    AnnotatedStatement:
      allOf:
        - $ref: '#/components/schemas/Statement'
        - type: object
          properties:
            servers:
              type: array
              uniqueItems: true
              items:
                type: string
                description: known catalog servers already queried in distributed search scenario
            annotations:
              type: object
              additionalProperties:
                type: object
                description: additional properties to tune query execution
              example:
                queryLanguage: SPARQL
                timeout: 30
                withTotalCount: false
    Asset:
      type: object
      properties:
        assetHash:
          type: string
        id:
          type: string
        status:
          $ref: '#/components/schemas/AssetStatus'
        issuer:
          type: string
        validatorDids:
          description: >-
            The credentialSubjects of the parties that validated (parts of) the
            credential.
          type: array
          items:
            type: string
        uploadDatetime:
          type: string
          format: date-time
          example: '2022-03-01T13:00:00Z'
          description: The time stamp (ISO8601) when the asset was uploaded.
        statusDatetime:
          type: string
          format: date-time
          example: '2022-05-11T15:30:00Z'
          description: >-
            The last time stamp (ISO8601) the status changed (for this
            Catalogue)
        contentType:
          type: string
          description: MIME content-type of the uploaded asset (e.g. application/ld+json, application/pdf)
          example: 'application/ld+json'
        fileSize:
          type: integer
          format: int64
          description: Size of the uploaded asset in bytes
        warnings: &warningsProperty
          type: array
          description: >-
            Warnings issued during processing (e.g. triples removed due to reserved namespace filtering).
            The operation succeeded for all remaining data. Absent or empty when no warnings occurred.
          items:
            type: string
          example:
            - "2 triple(s) were removed from your upload because they use the reserved internal namespace
               <https://projects.eclipse.org/projects/technology.xfsc/federated-catalogue/meta#>.
               This namespace is reserved for internal catalogue use only and cannot be set by external clients."
        humanReadableId:
          type: string
          description: >-
            IRI of the linked human-readable representation (e.g. a PDF document),
            if one has been attached to this machine-readable asset. Absent when no link exists.
        machineReadableId:
          type: string
          description: >-
            IRI of the linked machine-readable asset, if this asset is a human-readable
            representation linked to a machine-readable parent. Absent when no link exists.
    AssetEnrichmentResponse:
      type: object
      description: Response returned when an existing non-RDF asset is enriched with RDF metadata.
      required:
        - assetId
        - triplesAdded
        - triplesRejected
      properties:
        assetId:
          type: string
          description: IRI (subjectId) of the enriched asset.
        triplesAdded:
          type: integer
          description: Number of RDF triples written to the graph store after namespace filtering.
        triplesRejected:
          type: integer
          description: Number of triples filtered out due to protected namespace policy.
    AssetResult:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Asset'
        content:
          type: string
    Assets:
      allOf:
        - $ref: '#/components/schemas/ResultPage'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/AssetResult'
    AssetStatus:
      type: string
      enum:
        - active
        - eol
        - deprecated
        - revoked
    AssetVersion:
      type: object
      required: [version, createdAt, createdBy, status, isCurrent]
      properties:
        version:
          type: integer
          description: '1-based version ordinal.'
        createdAt:
          type: string
          format: date-time
          description: 'Timestamp when this version was created (Envers revision timestamp).'
        createdBy:
          type: string
          description: 'Issuer DID of the asset at this version.'
        status:
          $ref: '#/components/schemas/AssetStatus'
        isCurrent:
          type: boolean
          description: 'Whether this is the current (latest) version.'
        changeComment:
          type: string
          nullable: true
          description: 'Optional change note provided at upload time.'
    AssetVersionList:
      type: object
      required: [id, total, versions]
      properties:
        id:
          type: string
          description: 'The asset IRI.'
        total:
          type: integer
          description: 'Total number of versions.'
        versions:
          type: array
          items:
            $ref: '#/components/schemas/AssetVersion'
          description: 'Descending list (newest first) for the requested page.'
    ComplianceCheckRequest:
      type: object
      required: [ frameworkProfileId, credential ]
      properties:
        frameworkProfileId:
          type: string
          description: The trust-framework profile ID to check against (e.g. "mock-2026")
        credential:
          type: string
          description: Raw VP JWT credential to submit to the compliance service

    ComplianceCheckResult:
      type: object
      properties:
        conforms:
          type: boolean
          description: True when the compliance service issued an attestation
        failureCategory:
          type: string
          nullable: true
          description: Set when conforms is false; describes how the check failed (currently UNVERIFIABLE_ATTESTATION)
        attestationCredential:
          type: string
          nullable: true
          description: Raw JWT compliance credential returned by the service (present only on conforms=true)

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    GraphDatabaseStatus:
      type: object
      properties:
        activeBackend:
          type: string
          description: Currently active graph database backend
        connected:
          type: boolean
          description: Whether the graph database is reachable
        claimCount:
          type: integer
          format: int64
          description: Number of claims in the graph database
        version:
          type: string
          description: Graph database version or implementation info
        rebuildNeeded:
          type: boolean
          description: |
            True when the active graph store has no claims but RDF assets exist in
            storage — typical after a backend switch or fresh start. The admin UI
            surfaces a rebuild prompt that calls `POST /admin/graph/rebuild`. Non-RDF
            assets are excluded from this check because they do not produce graph
            claims even after a successful rebuild.
        rdfAssetCount:
          type: integer
          format: int64
          description: |
            Number of active RDF assets in storage that would be re-indexed by a
            rebuild. Surfaced alongside `rebuildNeeded` so the UI can show how many
            assets the rebuild will process.
    GraphDatabaseSwitchResult:
      type: object
      properties:
        message:
          type: string
          description: Human-readable status message

    GraphStatus:
      type: object
      properties:
        backend:
          type: string
          description: The graph database backend type (NEO4J, FUSEKI, NONE)
        enabled:
          type: boolean
          description: Whether the graph store is enabled
        healthy:
          type: boolean
          description: Whether the graph store backend is healthy
        activeAssetCount:
          type: integer
          format: int64
          description: Number of active assets in PostgreSQL storage
        claimCountInGraph:
          type: integer
          format: int64
          description: Number of claim triples/nodes in the graph database
        assetCountInGraph:
          type: integer
          format: int64
          description: Number of distinct assets in the graph database
        syncAssessment:
          type: string
          description: Sync assessment (empty, in-sync, out-of-sync, unknown, disabled)
    KeycloakAdminUrl:
      type: object
      properties:
        url:
          type: string
          description: Keycloak Admin Console URL for the catalogue realm
    OntologyImpactEntry:
      type: object
      description: >-
        One runtime-uploaded ontology and its contribution to each
        registered trust-framework base class.
      properties:
        id:
          type: string
          description: Schema identifier
        name:
          type: string
          description: >-
            Display name for the ontology. Derived from the parsed
            owl:Ontology IRI when present; falls back to the schema id.
        uploadedAt:
          type: string
          format: date-time
          description: When the ontology was uploaded
        contributions:
          type: object
          description: >-
            For each registered base-class name, the number of distinct
            rdfs:subClassOf+ descendants reachable from the base class's primary
            root and additional_roots, aggregated across active
            trust-framework bundles. Base classes with zero contributions are
            omitted. Empty when parseError is true.
          additionalProperties:
            type: integer
            format: int32
        parseError:
          type: boolean
          default: false
          description: >-
            True when the ontology could not be parsed or the subclass
            walk timed out. The contributions map will be empty; the UI
            should render a warning row so the admin does not conclude
            the ontology is safe to ignore.
        parseErrorMessage:
          type: string
          nullable: true
          description: >-
            Human-readable explanation when parseError is true. Null
            otherwise.
      required:
        - id
        - name
        - contributions
        - parseError
    OntologyImpactList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OntologyImpactEntry'
        noActiveBundles:
          type: boolean
          default: false
          description: >-
            True when no trust-framework bundles are active. In that case
            contributions cannot be computed for any ontology; the UI
            should surface a banner explaining that the OWL toggle has no
            base classes to gate.
      required:
        - items
        - noActiveBundles
    OntologySchema:
      type: object
      properties:
        ontologies:
          description: 'SchemaIds of ontologies, defining the terms of a schema'
          type: array
          items:
            type: string
            example: schemaId
        shapes:
          description: 'SchemaIds of shapes (SHACL Shapes Constraint Language) used to validate instances against the schema.'
          type: array
          items:
            type: string
            example: schemaId
        vocabularies:
          description: 'SchemaIds of controlled vocabularies used in the schema'
          type: array
          items:
            type: string
            example: schemaId
        jsonSchemas:
          description: 'SchemaIds of JSON Schemas used to validate JSON assets.'
          type: array
          items:
            type: string
            example: schemaId
        xmlSchemas:
          description: 'SchemaIds of XML Schemas (XSD) used to validate XML assets.'
          type: array
          items:
            type: string
            example: schemaId
    Parameters:
      type: object
      additionalProperties:
        type: object
      example:
        name: "John"
        limit: 10
        offset: 5
    Participant:
      type: object
      properties:
        id:
          type: string
          description: Global ID of the participant
        name:
          type: string
        publicKey:
          type: string
        asset:
          type: string
    Participants:
      allOf:
        - $ref: '#/components/schemas/ResultPage'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Participant'
    ProvenanceCredential:
      type: object
      required: [ id, assetId, assetVersion, issuer, issuedAt, provenanceType, credentialFormat ]
      properties:
        id:
          type: integer
          format: int64
          description: Internal surrogate key of the persisted provenance credential.
        assetId:
          type: string
          description: IRI of the asset this credential is attached to.
        assetVersion:
          type: integer
          description: 1-based Envers version ordinal the credential is linked to.
        credentialId:
          type: string
          description: VC id field (unique per asset).
        issuer:
          type: string
          description: DID of the VC issuer.
        issuedAt:
          type: string
          format: date-time
          description: issuedDateTime extracted from the VC.
        provenanceType:
          type: string
          enum: [ CREATION, DERIVATION, ATTRIBUTION, MODIFICATION, GENERATION, USAGE, ASSOCIATION, DELEGATION ]
          description: >
            Provenance relation type of the primary PROV-O predicate detected on
            credentialSubject. A single credential may carry several recognised predicates; every
            recognised predicate is projected to the graph store, while this field records the type
            of the first one for relational filtering. Predicate mapping: CREATION=wasGeneratedBy,
            DERIVATION=wasDerivedFrom, ATTRIBUTION=wasAttributedTo, MODIFICATION=wasRevisionOf,
            GENERATION=generated, USAGE=used, ASSOCIATION=wasAssociatedWith,
            DELEGATION=actedOnBehalfOf.
        credentialFormat:
          type: string
          enum: [ JSONLD, JSONLD_JWT, JWT ]
          description: Detected credential format.
        credentialContent:
          type: string
          description: Raw VC payload (JSON-LD or JWT string).
        verified:
          type: boolean
          description: Whether this credential has been verified.
        verificationTimestamp:
          type: string
          format: date-time
          nullable: true
          description: When the last verification was performed.
        verificationResult:
          $ref: '#/components/schemas/ProvenanceVerificationResult'
    ProvenanceCredentials:
      allOf:
        - $ref: '#/components/schemas/ResultPage'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/ProvenanceCredential'
    ProvenanceVerificationResult:
      type: object
      properties:
        isValid:
          type: boolean
          description: Overall validity of the credential.
        verificationTimestamp:
          type: string
          format: date-time
        verificationMethod:
          type: string
          description: DID verification method used.
        issuerResolutionStatus:
          type: string
          enum: [ RESOLVED, UNRESOLVABLE, TEMPORARILY_UNAVAILABLE ]
          description: Result of DID resolution for the issuer.
        issuedDateTime:
          type: string
          format: date-time
        signatureValid:
          type: boolean
        credentialExpiryValid:
          type: boolean
        validatorDids:
          type: array
          items:
            type: string
        errors:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string

    QueryInfo:
      type: object
      properties:
        backend:
          type: string
          example: "NEO4J"
        queryLanguage:
          $ref: '#/components/schemas/QueryLanguage'
        contentType:
          type: string
          example: "application/opencypher-query"
        enabled:
          type: boolean
          example: true
        exampleQuery:
          type: string
        documentation:
          type: string
    QueryLanguage:
      type: string
      enum:
        - OPENCYPHER
        - SPARQL
      default: OPENCYPHER
    RebuildStatus:
      type: object
      properties:
        total:
          type: integer
          format: int64
          description: Total number of assets to process
        processed:
          type: integer
          format: int64
          description: Number of assets processed so far
        percentComplete:
          type: integer
          description: Completion percentage (0-100)
        running:
          type: boolean
          description: Whether a rebuild is currently running
        complete:
          type: boolean
          description: Whether the rebuild has completed
        failed:
          type: boolean
          description: Whether the rebuild has failed
        errorMessage:
          type: string
          description: Error message if the rebuild failed
        errors:
          type: integer
          format: int64
          description: Number of assets that failed during processing
        durationMs:
          type: integer
          format: int64
          description: Duration in milliseconds since rebuild started
    Result:
      type: object
      additionalProperties:
        type: object
    ResultPage:
      type: object
      properties:
        totalCount:
          type: integer
    Results:
      allOf:
        - $ref: '#/components/schemas/ResultPage'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Result'
    Role:
      type: string
      example: Ro-MU-CA
    SchemaModulePatch:
      type: object
      description: >-
        Merge-patch body for PATCH /admin/schema-validation/modules/{type}. At least
        one field must be present. Only the supplied fields are modified; absent fields
        are left unchanged.
      minProperties: 1
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          description: Desired enabled state of the schema validation module.
    SchemaResult:
      type: object
      properties:
        id:
          type: string
          description: 'The internal identifier of the schema.'
        warnings:
          type: array
          items:
            type: string
          description: 'Warnings generated during schema import (e.g. filtered protected namespace statements).'
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: 'Timestamp when the schema was first uploaded. Present on creation, null on updates.'
        version:
          type: integer
          nullable: true
          description: 'Current version number after this operation. Present on updates, null on creation.'
        previousVersion:
          type: integer
          nullable: true
          description: 'Version number before this operation. Null for first version or on creation.'
    SchemaValidationModule:
      type: object
      properties:
        type:
          type: string
          description: Module type (SHACL, JSON_SCHEMA, XML_SCHEMA, OWL)
        name:
          type: string
          description: Display name
        description:
          type: string
          description: Module description
        schemaCount:
          type: integer
          format: int64
          description: Number of schemas for this module
        enabled:
          type: boolean
          description: Whether this module is active
    SchemaValidationStatus:
      type: object
      properties:
        totalSchemaCount:
          type: integer
          format: int64
          description: Total number of schemas across all modules
        modules:
          type: array
          items:
            $ref: '#/components/schemas/SchemaValidationModule'
    SchemaVersion:
      type: object
      properties:
        version:
          type: integer
          description: '1-based version ordinal.'
        createdAt:
          type: string
          format: date-time
          description: 'Timestamp when this version was created.'
        isCurrent:
          type: boolean
          description: 'Whether this is the current (latest) version.'
    SchemaVersionList:
      type: object
      properties:
        schemaId:
          type: string
          description: 'The schema identifier.'
        versions:
          type: array
          items:
            $ref: '#/components/schemas/SchemaVersion'
    Session:
      type: object
      properties:
        userId:
          type: string
        creationDatetime:
          type: string
          format: date-time
        status:
          type: string
        roleIds:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    Statement:
      type: object
      properties:
        statement:
          type: string
          example: Match (m:Movie) where m.released > 2000 RETURN m
        parameters:
          $ref: '#/components/schemas/Parameters'
      required:
        - statement
    StoredValidationResult:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique ID of the stored validation result
        assetIds:
          type: array
          items:
            type: string
          description: Asset subject IRI(s) that were validated
        validatorIds:
          type: array
          items:
            type: string
          description: Validator IDs (schema or trust framework) used for validation
        validatorType:
          type: string
          enum: [SHACL, JSON_SCHEMA, XML_SCHEMA, TRUST_FRAMEWORK]
          description: Distinguishes on-demand schema validation from external trust framework validation results
        conforms:
          type: boolean
          description: True if the asset passed validation
        validatedAt:
          type: string
          format: date-time
          description: Timestamp of the validation run
        report:
          type: string
          nullable: true
          description: Serialised validation report (SHACL Turtle / JSON violations / XSD error)
        contentHash:
          type: string
          description: SHA-256 hex digest of core fields for offline tamper detection
        graphSyncStatus:
          type: string
          enum: [SYNCED, FAILED]
          nullable: true
          description: Graph database synchronization status. FAILED indicates the result could not be written to the triple store and requires manual intervention.
        createdAt:
          type: string
          format: date-time
          description: Timestamp of record creation in the database
        outdated:
          type: boolean
          description: True if the result has been superseded by a newer validation run or asset lifecycle event
        outdatedReason:
          type: string
          enum: [ASSET_UPDATED, ASSET_REVOKED]
          nullable: true
          description: Reason the result was marked outdated; null when outdated is false

    TrustFrameworkBaseClassPatch:
      type: object
      description: >-
        Merge-patch body for PATCH /admin/trust-frameworks/{bundleId}/base-classes/{baseClassName}.
        At least one field must be present. Only the supplied fields are modified;
        absent fields are left unchanged.
      minProperties: 1
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          description: Desired enabled state of the base class within the bundle.
    TrustFrameworkBundleEffectiveConfig:
      type: object
      description: >-
        Effective compliance configuration of a bundle after applying any per-bundle
        overrides on top of the YAML baseline. Resolved by the catalogue server at
        request time; read-only.
      properties:
        clientType:
          type: string
        serviceUrl:
          type: string
        compliancePath:
          type: string
        apiVersion:
          type: string
        timeoutSeconds:
          type: integer
        trustAnchorUrl:
          type: string
    TrustFrameworkBundleEntry:
      type: object
      properties:
        id:
          type: string
          description: Bundle profile ID (e.g. gaia-x-2511)
        baseClasses:
          type: object
          additionalProperties:
            type: boolean
          description: Per-base-class enabled state for this bundle, keyed by base-class name.
        effectiveConfig:
          $ref: '#/components/schemas/TrustFrameworkBundleEffectiveConfig'
        overriddenFields:
          type: array
          description: >-
            Names of effective-config fields whose value currently comes from a
            persisted override (DB row) rather than the bundle YAML. Allows the
            UI to distinguish operator-set values from YAML defaults.
          items:
            type: string
    TrustFrameworkEntry:
      type: object
      properties:
        id:
          type: string
          description: Trust framework identifier
        name:
          type: string
          description: Display name
        enabled:
          type: boolean
          description: Whether this framework is active
        bundles:
          type: array
          items:
            $ref: '#/components/schemas/TrustFrameworkBundleEntry'
          description: Per-bundle base-class states for this trust framework family.
    TrustFrameworkPatch:
      type: object
      description: >-
        Merge-patch body for PATCH /admin/trust-frameworks/{id}. At least one field
        must be present. Only the supplied fields are modified; absent fields are
        left unchanged.
      minProperties: 1
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          description: Desired enabled state of the trust framework family.
    TrustFrameworkPublicEntry:
      type: object
      properties:
        id:
          type: string
          description: Family ID (e.g. "gaia-x", "mock")
        name:
          type: string
          description: Human-readable family name
        profiles:
          type: array
          items:
            type: string
          description: Profile IDs registered for this family (e.g. ["gaia-x-2511"])

    User:
      type: object
      properties:
        participantId:
          type: string
          description: Global ID of the associated participant
          example: ExampleCompany
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        email:
          type: string
        roleIds:
          type: array
          items:
            $ref: '#/components/schemas/Role'
      required:
        - participantId
        - firstName
        - lastName
        - email
    UserProfile:
      allOf:
        - $ref: '#/components/schemas/User'
        - type: object
          properties:
            id:
              type: string
              description: Internal catalogue user id
              example: ExampleCompany-John-Doe
            username:
              type: string
              example: John Doe
          required:
            - id
            - username
    UserProfiles:
      allOf:
        - $ref: '#/components/schemas/ResultPage'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/UserProfile'
    ValidationReport:
      type: object
      required:
        - conforms
      properties:
        conforms:
          type: boolean
          description: True if validation passed with no violations
        violations:
          type: array
          items:
            $ref: '#/components/schemas/ValidationViolation'
          description: List of constraint violations (empty if conforms=true)
        rawReport:
          type: string
          nullable: true
          description: Serialised raw report (SHACL Turtle for RDF; error message for JSON/XML)

    ValidationRequest:
      type: object
      required:
        - assetIds
      properties:
        assetIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 20
          description: >
            Asset IRIs to validate (1 up to the configured maximum, default 20 - see
            `federated-catalogue.validation.max-assets-per-request`). A single-ID request runs full type-based dispatch
            (SHACL for RDF assets, JSON Schema for JSON, XML Schema for XML).
            Multiple IDs merge all assets into a single data graph for SHACL-only validation;
            all assets must be RDF assets in that case.
        schemaIds:
          type: array
          items:
            type: string
          description: >
            Optional schema IDs to validate against. For single-asset requests, each schema
            must match the asset type (SHACL shape for RDF, JSON Schema for JSON, XML Schema
            for XML). For multi-asset requests, each must be a SHACL shape.
            Mutually exclusive with validateAgainstAllSchemas=true.
        validateAgainstAllSchemas:
          type: boolean
          default: false
          description: >
            If true, validate against all stored schemas matching the asset type (single-asset)
            or all stored SHACL shapes (multi-asset).

    ValidationResponse:
      type: object
      required:
        - assetIds
        - schemaIds
        - conforms
        - validatedAt
        - validationResultIds
      properties:
        assetIds:
          type: array
          items:
            type: string
          description: Asset IRIs that were validated
        schemaIds:
          type: array
          items:
            type: string
          description: Schema IDs that were validated against
        conforms:
          type: boolean
          description: True if all assets passed validation against all schemas
        validatedAt:
          type: string
          format: date-time
          description: Timestamp of the validation run
        validationResultIds:
          type: array
          items:
            type: integer
            format: int64
          minItems: 1
          description: >
            IDs of all ValidationResult records stored for this request, one per validator paradigm that ran.
        report:
          $ref: '#/components/schemas/ValidationReport'

    ValidationViolation:
      type: object
      properties:
        focusNode:
          type: string
          description: The RDF resource that violated the constraint
        resultPath:
          type: string
          description: The property path involved in the violation
        message:
          type: string
          description: Human-readable violation message
        severity:
          type: string
          enum: [VIOLATION, WARNING, INFO]
          description: Violation severity level
        sourceShape:
          type: string
          description: The SHACL shape that was violated

    VerificationResult:
      type: object
      properties:
        verificationTimestamp:
          type: string
          format: date-time
        lifecycleStatus:
          type: string # does the asset have a lifecycle status in this catalogue?
          description: Lifecycle-state an asset would get, if it would be added to the catalogue.
        issuer:
          type: string # contains the id of the issuers credential if available
          description: ID of the issuer's credential, if available.
        issuedDateTime:
          type: string
          format: date-time
        validatorDids:
          type: array
          items:
            type: string
            description: The DIDs of validators that signed parts of the credential
        warnings: *warningsProperty
        baseClass:
          type: string
          description: >-
            Resolved trust-framework base-class name (e.g. "Participant", "ServiceOffering").
            Absent for non-credential RDF content.
          example: Participant
        frameworkProfileId:
          type: string
          description: >-
            Bundle profile identifier that resolved the base class (e.g. "gaia-x-2511").
            Absent for non-credential RDF content.
          example: gaia-x-2511
        name:
          type: string
          description: Display name of the credential holder, or the issuer DID if no holder is present.
        publicKey:
          type: string
          description: >-
            DID URI of the first validator that signed the credential. Absent when no validators are present.
        claims:
          type: object
          additionalProperties: true
          description: >-
            Raw claims from the credential, keyed by claim property URI. Single values are
            strings; multi-valued properties are arrays of strings.
      required:
        - verificationTimestamp
        - lifecycleStatus
        - issuer
        - issuedDateTime
        - validatorDids
        - warnings
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Forbidden. The user does not have the permission to execute this
        request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        May contain hints how to solve the error or indicate what went wrong at
        the server. Must not outline any information about the internal
        structure of the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: >-
        May contain hints how to solve the error or indicate what was wrong in
        the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: HTTP Conflict 409
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unprocessible:
      description: HTTP Unprocessible Entity 422
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: >-
        The Content-Type indicates a query language not supported by the active
        graph database backend. Check GET /query/info for the supported language.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    OffsetParam:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
      required: false
      description: The number of items to skip before starting to collect the result set.
    LimitParam:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
      required: false
      description: The number of items to return.
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
tags:
  - name: Assets
    description: >-
      Manage assets in the Catalogue. Assets can be RDF credentials (JSON-LD
      Verifiable Presentations containing Verifiable Credentials), non-credential 
      RDF data (plain RDF triples), or non-RDF files. RDF content is automatically 
      verified and all claims or triples extracted to the graph database. Non-RDF 
      content is stored as-is. Assets are referenced by their sha256 hash. Catalogues 
      synchronize by exchanging changesets (lists of hashes) with peer Catalogues 
      and downloading any assets not yet locally available.
    externalDocs:
      description: Find out more
      url: https://docs.gaia-x.eu
  - name: Query
    description: Send graph queries to this Catalogue.
  - name: Schemas
    description: >-
      Schemas define the format of assets in the catalogue. Supported types include
      RDF schemas (ontologies, shapes, vocabularies) as well as non-RDF schemas
      (JSON Schema, XML Schema).
  - name: Verification
    description: The Catalogue provides a verification service for e.g. checking the syntax
  - name: Participants
    description: Participant Management operations
  - name: Users
    description: User Management operations
  - name: Roles
    description: Role Managemet operations
  - name: Session
    description: Management for auth sessions in the catalogue
  - name: Admin
    description: Administration dashboard and system management operations.
  - name: AdminTrustFrameworks
    description: Trust framework configuration and management.
  - name: AdminSchemaValidation
    description: Schema validation module configuration.
  - name: AdminGraph
    description: Graph database administration — status, backend switching, and rebuild operations.
  - name: Validations
    description: Stored validation results.
  - name: Compliance
    description: Trust-framework compliance check endpoints.
  - name: TrustFrameworks
    description: Public discovery of enabled trust frameworks.
paths:
  /admin/me:
    get:
      tags:
        - Admin
      summary: Check if the current user has admin access
      operationId: checkAdminAccess
      security:
        - jwt: []
      responses:
        '200':
          description: User has admin access
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /admin/stats:
    get:
      tags:
        - Admin
      summary: Get dashboard statistics
      operationId: getAdminStats
      security:
        - jwt: []
      responses:
        '200':
          description: Dashboard statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminStats'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/health:
    get:
      tags:
        - Admin
      summary: Get component health overview
      operationId: getAdminHealth
      security:
        - jwt: []
      responses:
        '200':
          description: Component health status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminHealthStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/keycloak-url:
    get:
      tags:
        - Admin
      summary: Get the Keycloak Admin Console URL for embedding
      operationId: getKeycloakAdminUrl
      security:
        - jwt: []
      responses:
        '200':
          description: Keycloak Admin Console URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeycloakAdminUrl'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/trust-frameworks:
    get:
      tags:
        - AdminTrustFrameworks
      summary: List all registered trust frameworks
      operationId: getTrustFrameworks
      security:
        - jwt: []
      responses:
        '200':
          description: List of trust frameworks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrustFrameworkEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/trust-frameworks/{id}:
    patch:
      tags:
        - AdminTrustFrameworks
      summary: Partially update a trust framework
      description: >-
        Applies a merge-patch to the identified trust framework. Only the fields
        present in the request body are modified; absent fields are left unchanged.
        At least one field must be supplied (minProperties: 1). Unknown fields are
        rejected (additionalProperties: false).
      operationId: patchTrustFramework
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/TrustFrameworkPatch'
      responses:
        '200':
          description: Trust framework updated
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/trust-frameworks/bundles/{bundleId}:
    patch:
      tags:
        - AdminTrustFrameworks
      summary: Merge-patch external client identifiers of a trust-framework bundle
      description: >-
        Merge-patch semantics (RFC 7396): only fields present in the body are modified.
        Overrides the per-bundle compliance endpoint URL, API version, timeout,
        client implementation key, and trust-anchor list URL. The bundle YAML remains
        the baseline; absent override fields fall back to the YAML value. The change
        takes effect on the next compliance call against the bundle — no restart is
        required. At least one field must be present (minProperties: 1).
      operationId: patchTrustFrameworkBundleConfig
      security:
        - jwt: [ ]
      parameters:
        - name: bundleId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: true
              description: >-
                Free-form merge-patch object. Recognised keys are clientType,
                serviceUrl, compliancePath, apiVersion, timeoutSeconds, trustAnchorUrl.
                Setting a key's value to a non-null primitive overrides the bundle
                YAML for that field. Setting a key's value to JSON null clears the
                override for that field (the YAML value is used again). Omitting a
                key leaves any existing override or YAML value unchanged. At least
                one key must be present.
      responses:
        '200':
          description: Bundle configuration updated
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - AdminTrustFrameworks
      summary: Clear all external-identifier overrides for a trust-framework bundle
      description: >-
        Removes any persisted overrides for the given bundle, restoring the bundle YAML
        as the sole source of compliance configuration. Idempotent — a bundle without
        an override row still returns 200. Use when an operator wants to revert all
        runtime adjustments at once; for partial reverts, PATCH with the desired
        fields instead.
      operationId: deleteTrustFrameworkBundleConfig
      security:
        - jwt: [ ]
      parameters:
        - name: bundleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Bundle overrides cleared (or already absent)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/trust-frameworks/{bundleId}/base-classes/{baseClassName}:
    patch:
      tags:
        - AdminTrustFrameworks
      summary: Merge-patch a single base class within a trust-framework bundle
      description: >-
        Merge-patch semantics (RFC 7396): only fields present in the body are modified.
        At least one field must be present.
      operationId: patchTrustFrameworkBaseClass
      security:
        - jwt: []
      parameters:
        - name: bundleId
          in: path
          required: true
          schema:
            type: string
        - name: baseClassName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/TrustFrameworkBaseClassPatch'
      responses:
        '200':
          description: Base-class state updated
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/schema-validation:
    get:
      tags:
        - AdminSchemaValidation
      summary: Get schema validation module status
      operationId: getSchemaValidationStatus
      security:
        - jwt: []
      responses:
        '200':
          description: Schema validation modules with status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaValidationStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/schema-validation/modules/{type}:
    patch:
      tags:
        - AdminSchemaValidation
      summary: Partially update a schema validation module
      description: >-
        Applies a merge-patch to the identified schema validation module. Only the
        fields present in the request body are modified. Disabling a module makes
        affected endpoints return `400 module_disabled:<MODULE>` (see `/assets/validate`
        and `/verification`). Storage of schemas is unaffected — stored schemas remain
        queryable through `/schemas/**` regardless of toggle state.


        **Scope of the `OWL` module toggle:** it controls only whether
        *runtime-uploaded* ontology extensions contribute their subclasses to the
        active trust-framework base classes. The deploy-time
        `verification.semantics` flag is a separate gate with different effects;
        see the arc42 chapter "Verification toggle interactions" for how they
        compose.
      operationId: patchSchemaModule
      security:
        - jwt: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - SHACL
              - JSON_SCHEMA
              - XML_SCHEMA
              - OWL
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SchemaModulePatch'
      responses:
        '200':
          description: Module updated
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/schema-validation/ontologies:
    get:
      tags:
        - AdminSchemaValidation
      summary: List uploaded ontologies and their subclass contributions to registered base classes
      description: >-
        Returns the runtime-uploaded ontologies currently consulted by the OWL
        module when it is enabled, with the number of subclasses each ontology
        contributes to each registered trust-framework base class (Participant,
        ServiceOffering, Resource for the Gaia-X 2511 bundle). Read-only —
        admins toggle the OWL module as a whole on
        `PATCH /admin/schema-validation/modules/{type}`. This endpoint surfaces
        what that toggle is gating.
      operationId: getOntologyImpact
      security:
        - jwt: []
      responses:
        '200':
          description: List of ontologies with per-base-class subclass counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OntologyImpactList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/graph-database:
    get:
      tags:
        - AdminGraph
      summary: Get graph database status
      operationId: getGraphDatabaseStatus
      security:
        - jwt: []
      responses:
        '200':
          description: Graph database status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphDatabaseStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/graph-database/switch:
    post:
      tags:
        - AdminGraph
      summary: Switch the graph database backend (requires restart)
      operationId: switchGraphDatabase
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                backend:
                  type: string
                  description: Target backend (NEO4J, FUSEKI, NONE)
              required:
                - backend
      responses:
        '200':
          description: Switch request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphDatabaseSwitchResult'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /admin/graph/rebuild:
    post:
      tags:
        - AdminGraph
      summary: Trigger an asynchronous graph rebuild
      operationId: triggerGraphRebuild
      security:
        - jwt: []
      responses:
        '202':
          description: Graph rebuild started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RebuildStatus'
        '409':
          description: A graph rebuild is already in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RebuildStatus'
        '503':
          description: Graph store is disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/graph/rebuild/status:
    get:
      tags:
        - AdminGraph
      summary: Get the current graph rebuild status
      operationId: getGraphRebuildStatus
      security:
        - jwt: []
      responses:
        '200':
          description: Current rebuild status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RebuildStatus'
  /admin/graph/status:
    get:
      tags:
        - AdminGraph
      summary: Get the current graph store status
      operationId: getGraphStatus
      security:
        - jwt: []
      responses:
        '200':
          description: Graph store status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphStatus'
  /assets:
    get:
      tags:
        - Assets
      summary: Get the list of asset metadata in the Catalogue
      operationId: readAssets
      security:
        - jwt: []
      parameters:
        - name: uploadTimerange
          in: query
          description: >-
            Filter for the time range when the asset was uploaded to the
            catalogue. The time range has to be specified as start time and
            end time as ISO8601 timestamp separated by a `/`.
          required: false
          example: 2022-03-01T13:00:00Z/2022-05-11T15:30:00Z
          schema:
            type: string
        - name: statusTimerange
          in: query
          description: >-
            Filter for the time range when the status of the asset was last
            changed in the catalogue. The time range has to be specified as
            start time and end time as ISO8601 timestamp separated by a `/`.
          required: false
          example: 2022-03-01T13:00:00Z/2022-05-11T15:30:00Z
          schema:
            type: string
        - name: issuers
          in: query
          description: >-
            Filter for the issuer of the credential. This is the unique ID of the
            Participant that has prepared the credential.
          required: false
          schema:
            type: array
            items:
              type: string
          explode: false
        - name: validators
          in: query
          description: >-
            Filter for a validator of the credential. This is the unique ID of the
            Participant that validated (part of) the credential.
          required: false
          schema:
            type: array
            items:
              type: string
          explode: false
        - name: statuses
          in: query
          description: Filter for the status of the asset.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AssetStatus'
          explode: false
        - name: ids
          in: query
          description: Filter for the id/credentialSubject of the credential.
          required: false
          schema:
            type: array
            items:
              type: string
          explode: false
        - name: hashes
          in: query
          description: Filter for the hash of the asset.
          required: false
          schema:
            type: array
            items:
              type: string
          explode: false
        - name: withMeta
          in: query
          description: Whether to include asset metadata in the response.
          required: false
          schema:
            type: boolean
            default: true
        - name: withContent
          in: query
          description: Whether to include asset content in the response.
          required: false
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of metadata of available assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assets'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Assets
      summary: Add a new asset to the catalogue
      description: >-
        Upload an asset. Non-RDF content is stored directly (HTTP 201).
        RDF content is automatically detected and routed: if the RDF subject IRI
        matches an existing non-RDF asset, the asset is enriched with metadata
        (HTTP 200, returns AssetEnrichmentResponse); otherwise the RDF is
        stored as a new or updated credential asset (HTTP 201, returns Asset).
        Human-readable assets (attachments uploaded via
        `/assets/{asset_id}/human-readable`) cannot be enriched with metadata —
        attempting to enrich one returns HTTP 422.
        Trust-framework base-class compliance is not enforced on upload: a
        credential whose subject type does not resolve to a known base class is
        still stored (HTTP 201). Use `POST /verification` with
        `requireBaseClass=true` to enforce base-class resolution.
      operationId: addAsset
      security:
        - jwt: []
      requestBody:
        description: >-
          The asset content. For JSON-LD credentials, use application/json,
          application/vc+ld+json, or application/vp+ld+json. For JWT-wrapped
          credentials use application/vc+jwt (VC) or application/vp+jwt (VP) —
          these are IANA-registered types per W3C VC-JOSE-COSE and are issued by
          the live GXDCH Compliance Service. The ICAM 24.07 variants
          application/vc+ld+json+jwt and application/vp+ld+json+jwt are also
          accepted for backward compatibility but are not IANA-registered.
          For non-credential RDF serializations, use text/turtle,
          application/n-triples, or application/rdf+xml — triples are extracted
          and stored in the graph, but schema validation is not performed.
          For non-RDF assets, use multipart/form-data or application/octet-stream
          (handled by the server outside the generated delegate pattern).
        content:
          application/json:
            schema:
              type: string
          application/ld+json:
            schema:
              type: string
          application/vc+ld+json:
            schema:
              type: string
          application/vp+ld+json:
            schema:
              type: string
          application/vc+jwt:
            schema:
              type: string
          application/vp+jwt:
            schema:
              type: string
          application/vc+ld+json+jwt:
            schema:
              type: string
          application/vp+ld+json+jwt:
            schema:
              type: string
          text/turtle:
            schema:
              type: string
          application/n-triples:
            schema:
              type: string
          application/rdf+xml:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: >-
            Non-RDF asset enriched with RDF metadata. Returned when the uploaded
            RDF payload matches the subject IRI of an existing non-RDF asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetEnrichmentResponse'
        '201':
          description: Created
          headers:
            location:
              description: URL of the added asset.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: >-
            Unprocessable entity. Returned when the upload describes a subject IRI
            that resolves to a human-readable attachment, which cannot be enriched
            with metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/validate:
    post:
      tags:
        - Assets
      summary: Validate one or more assets against stored schemas
      description: >
        Validates stored assets against SHACL, JSON Schema, or XML Schema depending on asset
        type and request size. A single-ID request runs full type-based dispatch: RDF assets
        validate via SHACL (and optionally JSON Schema / XML Schema if the serialisation
        matches); non-RDF assets validate via JSON Schema or XML Schema. A multi-ID request
        merges all asset content into a single data graph and validates via SHACL only
        (R₁ ∪ R₂ against S); all assets must be RDF assets. Maximum number of assets per request
        is configurable via `federated-catalogue.validation.max-assets-per-request` (default: 20).
      operationId: validateAssets
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
      responses:
        '200':
          description: Validation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '400':
          description: >-
            Client error. Includes `module_disabled:<MODULE>` when a schema validation
            module required by the request is administratively disabled
            (see `PUT /admin/schema-validation/modules/{type}`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Asset type is not validatable (not RDF or unsupported content type)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}:
    get:
      tags:
        - Assets
      summary: Read an asset by its IRI.
      description: >
        Returns a JSON-serialized Asset metadata object for any asset identified by its IRI.

        For RDF (JSON-LD) assets, the rawContent field is populated with the raw JSON-LD string.

        For any asset (RDF or non-RDF) that has bidirectional links to another representation,
        the humanReadableId or machineReadableId fields are populated.

        For non-RDF assets (PDF, images, binary files), the file content can be retrieved via
        GET /assets/{id}/human-readable or GET /assets/{id}/machine-readable.
      operationId: readAssetById
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset (DID, URN, or HTTP IRI)
          required: true
          schema:
            type: string
          examples:
            did:
              summary: DID Web identifier
              value: 'did:web:example.com:participant'
            urn:
              summary: UUID URN (non-RDF assets)
              value: 'urn:uuid:550e8400-e29b-41d4-a716-446655440000'
            http:
              summary: HTTP IRI
              value: 'https://example.org/asset/123'
        - name: version
          in: query
          description: Optional 1-based version ordinal. If provided, returns the asset content at that specific version.
          required: false
          schema:
            type: integer
            minimum: 1
      security:
        - jwt: []
      responses:
        '200':
          description: >
            The asset metadata as a JSON-serialized Asset object.
            For RDF (JSON-LD) assets, the rawContent field is populated with the raw JSON-LD string.
            For any asset with bidirectional links, humanReadableId or machineReadableId fields are populated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Assets
      summary: Update an asset in-place (versioned).
      description: >
        Updates an existing asset identified by its IRI. The update is applied in-place;
        Envers records the previous state as a new revision in assets_aud automatically.
        If no asset exists for the given IRI, the asset is created as version 1.
        Required permission: ASSET_UPDATE or ADMIN_ALL
      operationId: updateAsset
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: changeComment
          in: query
          description: Optional human-readable note for this version.
          required: false
          schema:
            type: string
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/ld+json:
            schema:
              type: string
          application/json:
            schema:
              type: string
          text/turtle:
            schema:
              type: string
          application/n-triples:
            schema:
              type: string
          application/rdf+xml:
            schema:
              type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/versions:
    get:
      tags:
        - Assets
      summary: Get version history for an asset.
      description: >
        Returns a paginated list of all versions of the asset, ordered descending (newest first).


        A "version" is one distinct content hash observed in the asset's audit history. Saves that
        only change non-content fields (linking a human-readable companion, lifecycle-status
        transitions, last-modified bookkeeping) reuse an existing hash and do not produce a new
        version entry — so attaching a provenance credential or a human-readable companion never
        advances the version count.


        Required permission: ASSET_READ or ADMIN_ALL
      operationId: readAssetVersions
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: 0-based page index.
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: size
          in: query
          description: Page size (1–100).
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      security:
        - jwt: []
      responses:
        '200':
          description: The version history of the asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVersionList'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/versions/{version}/revoke:
    post:
      tags:
        - Assets
      summary: Revoke a specific version of an asset.
      description: >
        Revokes the specified version of the asset. Only the current (latest) version can be revoked.
        Attempting to revoke a historical version returns 409 Conflict, because Envers snapshots are immutable.
        Required permission: ASSET_UPDATE or ADMIN_ALL
      operationId: revokeAssetVersion
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: 1-based version ordinal to revoke.
          required: true
          schema:
            type: integer
            minimum: 1
      security:
        - jwt: []
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVersion'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/human-readable:
    post:
      tags:
        - Assets
      summary: Upload and link a human-readable representation to a machine-readable asset
      description: >
        Uploads a human-readable document (e.g. PDF) and links it bidirectionally
        to the existing machine-readable asset identified by {id}. The human-readable document
        is stored as an independent asset with its own IRI.


        The uploaded part's Content-Type is matched against a family-aware allowlist intersected
        with a script-execution denylist. Admitted by default:


          - inert document and structured-data types — `application/pdf`, the Office Open XML word
            document type, `application/json`, `application/ld+json`, `application/xml`, and the
            YAML media types (`application/yaml`, `application/x-yaml`);
          - the entire `text/*` family (e.g. `text/plain`, `text/html`, `text/markdown`,
            `text/csv`);
          - the entire `image/*`, `audio/*`, and `video/*` families (e.g. `image/png`,
            `audio/mpeg`, `video/mp4`).


        Refused regardless of family — these types either execute in the browser when echoed
        back as the stored `Content-Type`, or carry opaque-binary risk:


          - scripting media types (`text/javascript`, `text/ecmascript`, `text/vbscript`,
            `application/javascript`, `application/ecmascript`, `application/x-javascript`);
          - `image/svg+xml` (SVG can carry inline script);
          - opaque or native-executable types (`application/octet-stream`,
            `application/x-msdownload`, `application/x-executable`, `application/x-sh`,
            `application/x-shockwave-flash`, `application/x-httpd-php`).


        Any other value is rejected with `400`. Operators can override both the allowlist and the
        denylist via the `federated-catalogue.assets.human-readable-content-types` and
        `human-readable-content-type-denylist` properties. Linking a companion does not advance
        the machine-readable asset's version counter.


        Multipart uploads are handled by the server outside the generated delegate pattern.
        Required permission: ASSET_CREATE or ADMIN_ALL
      operationId: uploadHumanReadable
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI of the machine-readable asset to link to
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Human-readable document (e.g. PDF)
      responses:
        '201':
          description: Created — the human-readable asset was stored and linked
          headers:
            location:
              description: URL of the new human-readable asset.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Assets
      summary: Replace the human-readable representation linked to a machine-readable asset
      description: >
        Replaces the content of an existing human-readable document linked to the machine-readable asset
        identified by {id}. The human-readable asset must already be linked — use POST to create the
        initial link. The IRI of the human-readable asset is preserved.
        Required permission: ASSET_UPDATE or ADMIN_ALL
      operationId: replaceHumanReadable
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI of the machine-readable asset
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Human-readable document
      responses:
        '200':
          description: OK — the human-readable asset content was replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      tags:
        - Assets
      summary: Download the human-readable representation linked to a machine-readable asset
      description: >
        Returns the binary content of the human-readable document linked to the asset.
        Required permission: ASSET_READ or ADMIN_ALL
      operationId: getHumanReadable
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI of the machine-readable asset
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The human-readable document with its original Content-Type header
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/machine-readable:
    get:
      tags:
        - Assets
      summary: Download the machine-readable asset linked to a human-readable representation
      description: >
        Returns the binary content of the machine-readable asset linked to this human-readable
        representation. Required permission: ASSET_READ or ADMIN_ALL
      operationId: getMachineReadable
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI of the human-readable asset
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The machine-readable asset content with its original Content-Type header
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/validations:
    get:
      tags:
        - Assets
      summary: Get stored validation results for an asset
      operationId: getAssetValidations
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of validation results for the asset
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /assets/{id}/compliance-check:
    post:
      tags:
        - Compliance
      summary: Run a compliance check for an asset
      operationId: runComplianceCheck
      security:
        - jwt: [ ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComplianceCheckRequest'
      responses:
        '200':
          description: Compliance check completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceCheckResult'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          description: Compliance service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Compliance service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'

  /assets/{id}/compliance-checks:
    get:
      tags:
        - Compliance
      summary: Get stored compliance check results for an asset
      operationId: getComplianceChecks
      security:
        - jwt: [ ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of compliance check results for the asset
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'

  /assets/{id}/provenance:
    post:
      tags:
        - Assets
      summary: Attach a provenance credential to an asset version.
      description: >
        Stores a VC 2.0 JSON-LD or VC-JWT provenance credential against the given asset version.
        If version is omitted the current version is used.


        Two `credentialSubject` shapes are accepted:


          - *Entity-centric* — `credentialSubject.id` equals `{assetId}:v{N}`. The versioned-asset
            IRI becomes the graph subject; the projected PROV-O triples decorate that subject.
          - *Activity-centric* — `credentialSubject.id` is the activity's own IRI (any absolute
            IRI). The credential MUST then declare `prov:generated` or `prov:used` (compact or
            expanded form) pointing at `{assetId}:v{N}` so the activity links back to a versioned
            asset. The activity IRI becomes the graph subject; the projected triples form the
            activity's star of relations.


        credentialSubject MUST declare at least one — and MAY declare several — of the supported
        W3C PROV-O predicates: prov:wasGeneratedBy, prov:wasDerivedFrom, prov:wasAttributedTo,
        prov:wasRevisionOf, prov:generated, prov:used, prov:wasAssociatedWith,
        prov:actedOnBehalfOf (compact prov:X or expanded http://www.w3.org/ns/prov#X form). Every
        recognised predicate is projected to the graph store as its own triple under the resolved
        graph subject; the predicate that appears first on credentialSubject is also recorded as
        the row's provenanceType for relational filtering.


        Attaching a provenance credential does not advance the asset version counter (the counter
        reflects distinct content hashes, not metadata events). VC 1.1 payloads and credentials
        using the CAT-internal namespace are rejected with 400. Duplicate credentialId returns 409.
        Required permission: ASSET_UPDATE or ADMIN_ALL
      operationId: addProvenanceCredential
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: 1-based target version ordinal. Defaults to the current version.
          required: false
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/ld+json:
            schema:
              type: string
              description: VC 2.0 JSON-LD payload
          application/vc+jwt:
            schema:
              type: string
              description: VC-JWT compact serialization
          application/json:
            schema:
              type: string
              description: VC 2.0 JSON-LD payload
      responses:
        '201':
          description: Provenance credential stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceCredential'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      tags:
        - Assets
      summary: List provenance credentials for an asset.
      description: >
        Returns a paginated list of provenance credentials sorted by issuedAt descending.
        Optionally filter by version. Required permission: ASSET_READ or ADMIN_ALL
      operationId: listProvenanceCredentials
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: Filter by 1-based version ordinal.
          required: false
          schema:
            type: integer
            minimum: 1
        - name: page
          in: query
          description: 0-based page index.
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: size
          in: query
          description: Page size (1–100).
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Paginated provenance credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceCredentials'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/provenance/verify:
    post:
      tags:
        - Assets
      summary: Verify all provenance credentials for an asset.
      description: >
        Verifies all provenance credentials for the asset (optionally filtered by version).
        Returns an aggregated result with per-credential status. Required permission: ASSET_UPDATE
        or ADMIN_ALL
      operationId: verifyAllProvenanceCredentials
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: Filter by 1-based version ordinal.
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Aggregated verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceVerificationResult'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/provenance/{credentialId}:
    get:
      tags:
        - Assets
      summary: Get a single provenance credential.
      description: >
        Returns the full provenance credential record including the raw VC content.
        Required permission: ASSET_READ or ADMIN_ALL
      operationId: getProvenanceCredential
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          description: VC id field of the provenance credential
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The provenance credential record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceCredential'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{id}/provenance/{credentialId}/verify:
    post:
      tags:
        - Assets
      summary: Verify a single provenance credential.
      description: >
        Validates the signature and DID of the given provenance credential and persists the
        extended verification result. Required permission: ASSET_UPDATE or ADMIN_ALL
      operationId: verifyProvenanceCredential
      security:
        - jwt: []
      parameters:
        - name: id
          in: path
          description: IRI identifier of the asset
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          description: VC id field of the provenance credential
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Verification result persisted and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceVerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /assets/{asset_hash}:
    delete:
      tags:
        - Assets
      summary: Completely delete an asset by its content hash
      description: >
        Unlike other asset endpoints which use IRI-based identification (/assets/{id}),
        the delete operation uses the SHA-256 content hash to guarantee unambiguous
        single-row targeting. See ADR 7 — Delete Operation Exception.


        For idempotent cascade-by-IRI semantics (every version, every linked companion, every
        provenance row), prefer DELETE /assets/by-id/{id}.
      operationId: deleteAsset
      security:
        - jwt: [ ]
      parameters:
        - name: asset_hash
          in: path
          description: Hash identifier of the asset
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/by-id/{id}:
    delete:
      tags:
        - Assets
      summary: Delete an asset and its linked companions by IRI
      description: >
        Removes the live asset row, any linked human-readable companion, and all associated
        provenance credentials for the asset identified by `id` (URL-encoded asset IRI).
        Historical audit revisions are preserved by design — see
        chapter 05_building_block_view of the architecture document.
        Data-subject-erasure requirements that demand audit-row removal are out of scope of this
        endpoint. The operation is idempotent — repeated calls on the same id return 204 even if
        no rows remain.

        Cross-participant scoping: when a live row is present, the caller's `participant_id` claim
        must match the issuer recorded on that row, otherwise the request is refused with 403.
        Requests against an unknown id always succeed with 204 and reveal nothing about the
        catalogue's contents.
      operationId: deleteAssetById
      security:
        - jwt: [ ]
      parameters:
        - name: id
          in: path
          description: URL-encoded asset IRI (subject identifier).
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deletion accepted (idempotent; no body)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /assets/{asset_hash}/revoke:
    post:
      tags:
        - Assets
      summary: Change the lifecycle state of an asset to revoked
      deprecated: true
      description: >
        DEPRECATED — use `POST /assets/{id}/versions/{version}/revoke` instead.
        Like the delete operation, the revoke endpoint uses the SHA-256 content hash
        to guarantee unambiguous single-row targeting. Only ACTIVE assets can be revoked.
        This hash-based revoke is superseded by the version-based variant
        (`POST /assets/{id}/versions/{version}/revoke`); the hash-based endpoint will be
        removed in a future major version once clients (Java client, BDD steps,
        performance harness) have migrated. See ADR 7 — Delete Operation Exception.
      operationId: revokeAsset
      security:
        - jwt: [ ]
      parameters:
        - name: asset_hash
          in: path
          description: Hash identifier of the asset
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Revoked
          headers:
            location:
              description: URL of the asset
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/ClientError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /validations/{id}:
    get:
      tags:
        - Validations
      summary: Get a single stored validation result by ID
      operationId: getValidationResult
      security:
        - jwt: [ ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The stored validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /query:
    get:
      tags:
        - Query
      summary: Retrieve an HTML website to send openCypher queries to the Catalogue
      description: 'Required permission: QUERY_EXECUTE or ADMIN_ALL'
      operationId: querywebsite
      security:
        - jwt: []
      responses:
        '200':
          description: HTML document that contains a query field for openCypher queries.
          content:
            text/html:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Query
      summary: Send a query to the Catalogue
      description: >
        Required permission: QUERY_EXECUTE or ADMIN_ALL.


        The SPARQL backend is RDF-star (SPARQL-Star) aware. Credential claims are projected as
        reified triples annotated with `cred:credentialSubject`
        (`http://www.w3.org/2018/credentials#credentialSubject`): each claim triple `s p o`
        appears in the graph as `<< s p o >> <cred:credentialSubject> <subject>`. Discovery
        queries that target the credential claims must therefore reach into the reification, for
        example:


        `SELECT ?subject WHERE { << ?subject a <https://example.org/dcs/1#ContractTemplate> >>
        <http://www.w3.org/2018/credentials#credentialSubject> ?subject }`.


        Asserted (non-reified) triples emitted by the catalogue itself — such as the
        machine-readable ↔ human-readable link predicates — are queryable with plain SPARQL.


        Content negotiation: the response body shape is selected by the `Accept` header.
        `application/json` (the default) returns the catalogue's legacy `Results` envelope
        with a flat `items` array of variable→value maps. `application/sparql-results+json`
        returns the W3C SPARQL 1.1 Results JSON document (`head.vars` and
        `results.bindings` with typed `{type, value, datatype?, "xml:lang"?}` entries) as
        defined in https://www.w3.org/TR/sparql11-results-json/. The W3C format is only
        available when the active graph store is SPARQL-capable; other backends return
        `406 Not Acceptable`.
      operationId: query
      parameters:
        - in: query
          name: timeout
          schema:
            type: integer
            default: 5
          required: false
        - in: query
          name: withTotalCount
          schema:
            type: boolean
            default: true
          required: false
      security:
        - jwt: []
      requestBody:
        description: >-
          Raw query text. Use Content-Type to indicate the query language:
          "application/sparql-query" for SPARQL, "application/opencypher-query"
          for openCypher.
        required: true
        content:
          application/sparql-query:
            schema:
              type: string
              example: "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10"
          application/opencypher-query:
            schema:
              type: string
              example: "MATCH (n:Resource) RETURN n.uri AS id, n.name AS name LIMIT 10"
      responses:
        '200':
          description: >-
            successful query. The response media type is selected by the
            client's `Accept` header: `application/json` returns the catalogue's
            legacy `Results` envelope, `application/sparql-results+json` returns
            the W3C SPARQL 1.1 Results JSON document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Results'
            application/sparql-results+json:
              schema:
                type: string
                description: >-
                  W3C SPARQL 1.1 Results JSON document. The body is a JSON
                  object with `head.vars` (list of projected variables) and
                  `results.bindings` (array of solution objects). Each binding
                  value is `{type, value}` with optional `datatype` or
                  `xml:lang`. See
                  https://www.w3.org/TR/sparql11-results-json/ for the full
                  schema.
                example: |
                  {
                    "head": { "vars": ["s","p","o"] },
                    "results": {
                      "bindings": [
                        {
                          "s": {"type":"uri","value":"http://example.org/service1"},
                          "p": {"type":"uri","value":"http://example.org/name"},
                          "o": {"type":"literal","value":"Example Service"}
                        }
                      ]
                    }
                  }
        '400': ## Malformed Message: The receveived request cannot be processed, either because its syntax is ## incorrect or forbidden query clauses are used. For instance, it is not allowed to manipulate data ## through the query endpoint
          $ref: '#/components/responses/ClientError'
        '406': ## Accept header asks for a representation the active graph store cannot produce
          ## (e.g. application/sparql-results+json against a non-SPARQL backend).
          $ref: '#/components/responses/ClientError'
        '408': ## Query Timeout: the query took longer than the configured timeout
          ## interval. The client needs to rewrite the query so it can be
          ## processed faster.
          $ref: '#/components/responses/ServerError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/ServerError'
  /query/info:
    get:
      tags:
        - Query
      summary: Get information about the active query backend
      description: 'Required permission: QUERY_EXECUTE or ADMIN_ALL'
      operationId: queryInfo
      security:
        - jwt: []
      responses:
        '200':
          description: Query backend information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryInfo'
        '500':
          $ref: '#/components/responses/ServerError'
  /query/search:
    post:
      tags:
        - Query
      summary: Run distributed search query in the Catalogue
      description: 'Required permission: QUERY_EXECUTE or ADMIN_ALL'
      operationId: search
      security:
        - jwt: []
      requestBody:
        description: JSON object containing query with parameters and annotations
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotatedStatement'
      responses:
        '200':
          description: successful query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Results'
        '400': ## Wrong query
          $ref: '#/components/responses/ClientError'
        '408': ## Query Timeout:
          $ref: '#/components/responses/ServerError'
        '422':
          $ref: '#/components/responses/Unprocessible'
        '500':
          $ref: '#/components/responses/ServerError'

  /schemas:
    get:
      tags:
        - Schemas
      summary: 'Get the full list of schemas (ontologies, shapes, vocabularies, JSON schemas, XML schemas).'
      description: 'The schema identifiers, returned by this endpoint can be used to download the schema files. Includes both RDF and non-RDF schema types. Required permission: SCHEMA_READ or ADMIN_ALL'
      operationId: getSchemas
      security:
        - jwt: []
      responses:
        '200':
          description: 'References to ontologies, shapes and vocabularies.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OntologySchema'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'          
    post:
      tags:
        - Schemas
      summary: 'Add a new Schema to the catalogue.'
      description: 'This endpoint accepts an ontology (OWL), shape (SHACL), controlled vocabulary (SKOS), JSON Schema, or XML Schema (XSD), which is added to the schemas of the catalogue. Required permission: SCHEMA_CREATE or ADMIN_ALL'
      operationId: addSchema
      security:
        - jwt: []
      requestBody:
        description: 'The file of the new schema: an ontology (OWL), shape (SHACL), controlled vocabulary (SKOS), JSON Schema, or XML Schema (XSD).'
        content:
          application/rdf+xml:
            schema:
              type: string
              description: 'OWL file describing the ontology of the schema or SKOS file describing the controlled vocabulary.'
          application/ld+json:
            schema:
              type: string
              description: 'OWL or SHACL file describing the ontology.'
          application/json:
              schema:
                type: string
                description: 'OWL or SHACL file describing the ontology.'
          text/turtle:
            schema:
              type: string
              description: 'SHACL file describing the ontology of the schema.'
          application/schema+json:
            schema:
              type: string
              description: 'JSON Schema file (Draft 2020-12).'
          application/xml:
            schema:
              type: string
              description: 'XML Schema (XSD) file.'
        required: true
      responses:
        '201':
          description: 'Created'
          headers:
            location:
              description: 'URL of the added Schema.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResult'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: 'Unprocessable Entity. The schema content is syntactically invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
  /schemas/latest:
    get:
      tags:
        - Schemas
      summary: 'Get the latest schema for a given type.'
      description: >-
        Behavior depends on schema type:

        **RDF types** (ontology, shape, vocabulary): Returns the **composite schema** — a merged union
        of all stored schemas of that type. This is meaningful because RDF schemas are additive
        (shapes and ontologies can be combined into a single graph).

        **Non-RDF types** (json, xml): Returns the **most recently uploaded** schema of that type.
        Compositing does not apply because JSON and XML schemas are self-contained and cannot be
        meaningfully merged.
      operationId: getLatestSchema
      parameters:
        - name: type
          in: query
          description: 'Type of the schema.'
          required: true
          schema:
            type: string
            enum:
              - ontology
              - shape
              - vocabulary
              - json
              - xml
        - name: term
          in: query
          description: 'The URI of the term of the requested schema e.g. `https://w3id.org/gaia-x/2511#ServiceOffering`'
          required: false
          schema:
            type: string
      security:
        - jwt: [ ]
      responses:
        '200':
          description: 'The latest schemas for the given type or term.'
          content:
            application/rdf+xml:
              schema:
                type: string
                description: 'OWL file describing the ontology of the schema or SKOS file describing the controlled vocabulary.'
            text/turtle:
              schema:
                type: string
                description: 'SHACL file describing the ontology of the schema.'
            application/schema+json:
              schema:
                type: string
                description: 'JSON Schema file.'
            application/xml:
              schema:
                type: string
                description: 'XML Schema (XSD) file.'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /schemas/{schemaId}:
    get:
      tags:
        - Schemas
      summary: Get a specific schema.
      description: 'Required permission: SCHEMA_READ or ADMIN_ALL'
      operationId: getSchema
      security:
        - jwt: []
      parameters:
        - name: schemaId
          in: path
          description: 'Identifier of the Schema.'
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: 'Optional version number. If provided, returns the schema at that specific version.'
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: 'The schema for the given identifier. Depending on the type of the schema, either an ontology, shape graph or controlled vocabulary is returned.'
          content:
            application/rdf+xml:
              schema:
                type: string
                description: 'OWL file describing the ontology of the schema or SKOS file describing the controlled vocabulary.'
            text/turtle:
              schema:
                type: string
                description: 'SHACL file describing the ontology of the schema.'
            application/schema+json:
              schema:
                type: string
                description: 'JSON Schema file.'
            application/xml:
              schema:
                type: string
                description: 'XML Schema (XSD) file.'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Schemas
      summary: 'Replace a schema. This is only allowed for ontologies with the same IRI.'
      description: 'Required permission: SCHEMA_UPDATE or ADMIN_ALL'
      operationId: updateSchema
      parameters:
        - name: schemaId
          in: path
          description: 'Identifier of the Schema.'
          required: true
          schema:
            type: string
      security:
        - jwt: [ ]
      requestBody:
        description: 'The new ontology (OWL file).'
        content:
          application/rdf+xml:
            schema:
              type: string
              description: 'OWL file describing the ontology.'
          application/ld+json:
            schema:
              type: string
              description: 'OWL or SHACL file describing the ontology.'
          application/json:
            schema:
              type: string
              description: 'OWL or SHACL file describing the ontology.'
          text/turtle:
            schema:
              type: string
              description: 'SHACL file describing the ontology of the schema.'
        required: true
      responses:
        '200':
          description: 'Updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResult'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Schemas
      summary: 'Delete a Schema'
      description: 'Required permission: SCHEMA_DELETE or ADMIN_ALL'
      operationId: deleteSchema
      security:
        - jwt: [ ]
      parameters:
        - name: schemaId
          in: path
          description: 'Identifier of the Schema'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Deleted Schema'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /schemas/{schemaId}/versions:
    get:
      tags:
        - Schemas
      summary: 'Get version history for a schema.'
      description: 'Returns an ordered list of all versions of the schema. Required permission: SCHEMA_READ or ADMIN_ALL'
      operationId: getSchemaVersions
      security:
        - jwt: []
      parameters:
        - name: schemaId
          in: path
          description: 'Identifier of the Schema.'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'The version history of the schema.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaVersionList'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /trust-frameworks:
    get:
      tags:
        - TrustFrameworks
      summary: List enabled trust frameworks and their profiles (public discovery)
      operationId: getTrustFrameworksPublic
      security:
        - jwt: [ ]
      responses:
        '200':
          description: List of enabled trust framework families with their profile IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrustFrameworkPublicEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /verification:
    get:
      tags:
        - Verification
      summary: Show a HTML page to verify (portions of) a signed credential
      operationId: verifyPage
      security:
        - jwt: [ ]
      responses:
        '200':
          description: >-
            HTML document that contains a query field to verify (portions of)
            credentials.
          content:
            text/html:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Verification
      summary: >-
        Send a JSON-LD document to verify with the information from the
        Catalogue
      operationId: verify
      parameters:
        - name: verifySemantics
          in: query
          description: 'To verify credential semantics or not'
          required: false
          schema:
            type: boolean
            default: true
        - name: verifyVPSignature
          in: query
          description: 'To verify VP signature or not'
          required: false
          schema:
            type: boolean
            default: true  
        - name: verifyVCSignature
          in: query
          description: 'To verify VC signature or not'
          required: false
          schema:
            type: boolean
            default: true
        - name: requireBaseClass
          in: query
          description: >-
            When true, reject a credential whose subject type cannot be resolved
            to a base class in any active trust-framework bundle — HTTP 422 when
            semantic verification is enabled (the default), otherwise HTTP 400.
            When false (the default), credentials with unresolvable types are
            accepted with a null base class. Useful for cross-framework demos
            against the bundled gaia-x-2511 / mock-2026 bundles.
          required: false
          schema:
            type: boolean
            default: false
        - name: framework
          in: query
          description: >-
            Trust-framework bundle identifier for disambiguation. Ignored when
            exactly one bundle is active. Required when the credential type is
            resolvable in more than one active bundle (e.g. two bundles both
            declare a "Participant" base class).
          required: false
          schema:
            type: string
      requestBody:
        description: >-
          The credential to verify. For JSON-LD credentials, use application/json,
          application/vc+ld+json, or application/vp+ld+json. For JWT-wrapped
          credentials use application/vc+jwt (VC) or application/vp+jwt (VP) —
          these are IANA-registered types per W3C VC-JOSE-COSE and are issued by
          the live GXDCH Compliance Service. The ICAM 24.07 variants
          application/vc+ld+json+jwt and application/vp+ld+json+jwt are also
          accepted for backward compatibility but are not IANA-registered.
        content:
          application/json:
            schema:
              type: string
          application/ld+json:
            schema:
              type: string
          application/vc+ld+json:
            schema:
              type: string
          application/vp+ld+json:
            schema:
              type: string
          application/vc+jwt:
            schema:
              type: string
          application/vp+jwt:
            schema:
              type: string
          application/vc+ld+json+jwt:
            schema:
              type: string
          application/vp+ld+json+jwt:
            schema:
              type: string
      security:
        - jwt: [ ]
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '400':
          $ref: '#/components/responses/ClientError'
        '422':
          $ref: '#/components/responses/Unprocessible'
        '500':
          $ref: '#/components/responses/ServerError'
  /participants:
    get:
      tags:
        - Participants
      summary: Get the registered participants
      operationId: getParticipants
      parameters:
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
#        - $ref: '#/components/parameters/OrderByParam'
#        - $ref: '#/components/parameters/AscendingParam'
      responses:
        '200':
          description: List of registered participants
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participants'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - jwt: []
    post:
      tags:
        - Participants
      summary: Register a new participant in the catalogue
      operationId: addParticipant
      requestBody:
        description: Participant credential
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '201':
          description: Created Participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
          headers:
            location: 
              description: 'URL of the added Participant'
              schema: 
                type: string
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - jwt: []
  /participants/{participantId}:
    get:
      tags:
        - Participants
      summary: Get the registered participant
      operationId: getParticipant
      parameters:
        - in: path
          name: participantId
          required: true
          description: The participantId to get.
          schema:
            type: string
      responses:
        '200':
          description: The requested participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - jwt: []
    put:
      tags:
        - Participants
      summary: Update a participant in the catalogue
      operationId: updateParticipant
      parameters:
        - in: path
          name: participantId
          required: true
          description: The participant to update.
          schema:
            type: string
      requestBody:
        description: Participant credential
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: Updated Participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - jwt: []
    delete:
      tags:
        - Participants
      summary: Delete a participant in the catalogue
      operationId: deleteParticipant
      parameters:
        - in: path
          name: participantId
          required: true
          description: The participant to delete.
          schema:
            type: string
      responses:
        '200':
          description: Deleted Participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - jwt: []
  /participants/{participantId}/users:
    get:
      tags:
        - Participants
      summary: Get all users of the registered participant
      operationId: getParticipantUsers
      parameters:
        - in: path
          name: participantId
          required: true
          description: The participant Id
          schema:
            type: string
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Users of the participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfiles'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - jwt: []
  /users:
    get:
      tags:
        - Users
      summary: List the registered users
      operationId: getUsers
      parameters:
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
#        - $ref: '#/components/parameters/OrderByParam'
#        - $ref: '#/components/parameters/AscendingParam'
      security:
        - jwt: [ ]
      responses:
        '200':
          description: List of usernames
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfiles'
        '400':
          $ref: '#/components/responses/ClientError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Users
      summary: Register a new user to the associated participant in the catalogue
      operationId: addUser
      requestBody:
        description: User profile
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      security:
        - jwt: [ ]
      responses:
        '201':
          description: Created User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
          headers:
            location: 
              description: 'URL of the added User'
              schema: 
                type: string
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
  /users/{userId}:
    get:
      tags:
        - Users
      summary: Get the user profile
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      security:
        - jwt: [ ]
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Users
      summary: Update the user profile
      operationId: updateUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: 'Updated user data, Participant ID will be ignored if provided.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      security:
        - jwt: [ ]
      responses:
        '200':
          description: Updated user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Users
      summary: Delete a user
      operationId: deleteUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      security:
        - jwt: [ ]
      responses:
        '200':
          description: Deleted user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
  /users/{userId}/roles:
    get:
      tags:
        - Users
      summary: Get roles of the user
      operationId: getUserRoles
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      security:
        - jwt: [ ]
      responses:
        '200':
          description: User roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Users
      summary: Update roles of the user
      operationId: updateUserRoles
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: List of roles which should be assigned to the user
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Role'
      security:
        - jwt: [ ]
      responses:
        '200':
          description: All assigned roles of the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          $ref: '#/components/responses/ClientError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /roles:
    get:
      tags:
        - Roles
      summary: Get all registered roles in the catalogue
      operationId: getAllRoles
      security:
        - jwt: [ ]
      responses:
        '200':
          description: All roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'

  /session:
    get:
      summary: Return the current authenticated session
      tags:
        - Session
      operationId: getCurrentSession
      security:
        - jwt: [ ]
      responses:
        '200':
          description: Get information on the current session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      summary: Close the current authenticated session
      tags:
        - Session
      operationId: logoutCurrentSession
      security:
        - jwt: [ ]
      responses:
        '200':
          description: The current session was closed
        '500':
          $ref: '#/components/responses/ServerError'