consent-management-API.yaml

openapi: 3.0.0
info:
  version: v1.0
  title: Consent Management API
  description: |
    This API provides a comprehensive set of endpoints for managing consent elements, consent purposes and consents.

    **Key Concepts:**

    - **Consent Element**: The most granular unit—a specific data point (e.g., email address) or processing action (e.g., sharing with third parties).
    - **Consent Purpose**: A logical grouping of elements under a single objective. Instead of asking users about each data point, you present the reason for the request (e.g., "Marketing Communications" includes email and phone).
    - **Consent**: The record of a user's decision. Tracks who approved what, when, and maintains the full status lifecycle (Created → Active → Expired/Revoked) with audit trail.
  contact:
    name: WSO2
    url: 'https://wso2.com/solutions/financial-services/'
    email: "architecture@wso2.com"
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://localhost:3000/api/v1
tags:
  - name: Consent Elements
    description: Manage Consent Elements
  - name: Consent Purposes
    description: Manage Consent Purposes
  - name: Consents
    description: Manage Consents
paths:
  /consents:
    post:
      summary: Initiate a new consent resource
      description: |
        This endpoint is used to initiate a new consent resource.

        Upon success, the system creates a **consent resource** with: A unique `consentId`

        **Purpose Access Rules:**
        When a purpose is referenced in a consent, the server validates that the consent is allowed to use it:
        - **Allowed** if `purpose.groupId == consent.groupId` — the purpose belongs to the same group as the consent.
        - **Allowed** if `purpose.groupId == orgId` — the purpose is an org-level purpose, available to all consents in the organization.
        - **Rejected** otherwise — a group-specific purpose from a different group cannot be used.

        **Element Resolution:**
        - `elements` within each purpose is optional. If omitted, all elements defined in the purpose
          are automatically included with `approved: false`.
        - If a subset of elements is provided, any unmentioned elements are resolved the same way —
          added to the response with `approved: false`.
      operationId: consents-POST
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "The unique identifier for the organization (e.g., the bank) that this consent belongs to."
          schema:
            type: string
            example: "ORG-001"
        - in: header
          name: group-id
          required: true
          description: "An identifier used to group related purposes and consents."
          schema:
            type: string
            example: "group-001"
      requestBody:
        description: The payload containing the consent data.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsentCreatePayload"
            example:
              type: "marketing"
              expirationTime: 1766383796000
              recurringIndicator: true
              dataAccessValidityDuration: 0
              frequency: 0
              purposes:
                - name: "marketing_communication_preferences"
                  version: "v1"
                  elements:
                    - name: "user_email"
                      approved: true
                      value: {}
                    - name: "user_mobile"
                      approved: true
                      value: {}
              attributes:
                department: "marketing"
              authorizations:
                - userId: "user1@example.com"
                  type: "authorisation"
                  status: "APPROVED"
                  resources:
                    accountIds: ["acc-123", "acc-456"]
      responses:
        "201":
          description: Successfully initiated the consent. The response body contains the details of the newly created consent resource, including its `id`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentCreatedResponse"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to create the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
    get:
      summary: Search for consents
      description: |
        Provides a powerful search capability to find consents based on various filter criteria like consent type, status, group ID, user ID, purpose, and element. Supports pagination.
        If purposeVersion is specified, purposeName must also be provided.
        If elementVersion is specified, at least one of elementName or elementNamespace must also be provided.

      operationId: consents-search-GET
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "Organisation ID."
          schema:
            type: string
            example: "ORG-001"
        - name: consentTypes
          in: query
          description: A comma-separated list of consent types to filter by (e.g., 'accounts,payments').
          schema:
            type: string
          example: "accounts,payments"
        - name: consentStatuses
          in: query
          description: "A comma-separated list of consent statuses to filter by (e.g., 'ACTIVE,REVOKED'). Valid values are: CREATED, ACTIVE, REJECTED, REVOKED, EXPIRED."
          schema:
            type: string
          example: "ACTIVE,CREATED"
        - name: groupIds
          in: query
          description: A comma-separated list of group IDs to filter by.
          schema:
            type: string
          example: "group-001,group-002"
        - name: userIds
          in: query
          description: A comma-separated list of end-user IDs to filter by.
          schema:
            type: string
          example: "user1@example.com,user2@example.com"
        - name: purposeName
          in: query
          description: Filter by consent purpose name. Returns consents that contain this purpose.
          schema:
            type: string
          example: "marketing_communication_preferences"
        - name: purposeVersion
          in: query
          description: Filter by a specific purpose version (e.g. "v2"). Requires purposeName to also be specified.
          schema:
            type: string
          example: "v2"
        - name: elementName
          in: query
          description: Filter by element name — returns consents that include this element.
          schema:
            type: string
          example: "user_email"
        - name: elementNamespace
          in: query
          description: Filter by element namespace — used together with elementName.
          schema:
            type: string
          example: "personal"
        - name: elementVersion
          in: query
          description: |
            Filter by a specific element version (e.g. "v2"). Requires at least one of elementName or elementNamespace to also be specified.
          schema:
            type: string
          example: "v2"
        - name: fromTime
          in: query
          description: The start of the time window for the search, as a Unix timestamp in milliseconds (integer).
          schema:
            type: integer
            format: int64
          example: 1702800000000
        - name: toTime
          in: query
          description: The end of the time window for the search, as a Unix timestamp in milliseconds (integer).
          schema:
            type: integer
            format: int64
          example: 1734422400000
        - name: limit
          in: query
          description: The maximum number of results to return in a single page. Used for pagination.
          schema:
            type: integer
            format: int32
          example: 10
        - name: offset
          in: query
          description: The number of results to skip. Used for pagination.
          schema:
            type: integer
            format: int32
          example: 0
      responses:
        "200":
          description: OK. Returns a list of consents matching the search criteria, along with pagination metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentSearchResponse"
        "400":
          description: Bad Request. The search parameters provided are invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consents/attributes:
    get:
      summary: Search consents by attribute key and value
      description: |
        Searches for consent IDs that have a specific attribute key, optionally filtered by value.

        **Search Modes:**
        - **By key only** (`?key=department`): Returns all consents with the specified attribute key
        - **By key and value** (`?key=department&value=sales`): Returns consents with exact key-value match

        Results are organization-scoped and sorted by consent ID.
      operationId: consents-attributes-GET
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "The unique identifier for the organization."
          schema:
            type: string
            example: "ORG-001"
        - name: key
          in: query
          required: true
          description: The attribute key to search for (required).
          schema:
            type: string
          example: "department"
        - name: value
          in: query
          required: false
          description: The attribute value to search for (optional). If provided, only consents with exact key-value match are returned.
          schema:
            type: string
          example: "sales"
      responses:
        "200":
          description: Successfully retrieved consent IDs matching the search criteria.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentAttributeSearchResponse"
        "400":
          description: Bad Request. The key parameter is missing or invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consents/{consentId}:
    get:
      summary: Retrieve a consent by its ID
      description: |
        Fetches the complete details of a specific consent resource using
        its unique `consentID`. This is used to check the status and details of a consent.

      operationId: consents-GET
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "The unique identifier for the organization (e.g., the bank) that this consent belongs to."
          schema:
            type: string
            example: "ORG-001"
        - in: path
          name: consentId
          required: true
          description: The unique identifier of the consent to retrieve.
          schema:
            type: string
      responses:
        "200":
          description: OK. The full details of the requested consent are returned in the response body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentRetrievalResponse"
        "400":
          description: Bad Request. The request was invalid, possibly due to a malformed `consentID` or missing headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
    put:
      summary: Update a consent resource by its ID
      description: |
        Endpoint to perform a full update on a consent resource, including its authorization resources and attributes, in a single operation.

        **Purpose Access Rules:**
        Same groupId validation as consent creation applies — a purpose can only be used if its `groupId`
        matches the consent's `groupId`, or if it is an org-level purpose (`purpose.groupId == orgId`).

        **Element Resolution:**
        - `elements` within each purpose is optional. If omitted, all elements defined in the purpose
          are automatically included with `approved: false`.
        - If a subset of elements is provided, any unmentioned elements are resolved the same way —
          added to the response with `approved: false`.

      operationId: consents-PUT
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "Organisation ID."
          schema:
            type: string
            example: "ORG-001"
        - in: header
          name: group-id
          required: true
          description: "The group ID of the consent. The group ID of a consent is immutable and cannot be changed — this header is used for validation only."
          schema:
            type: string
            example: "group-001"
        - name: consentId
          in: path
          description: The unique identifier of the consent to update.
          required: true
          schema:
            type: string
      requestBody:
        description: The full consent resource object with the desired updates.
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ConsentUpdateRequest"
            example:
              type: "accounts"
              expirationTime: 0
              recurringIndicator: false
              dataAccessValidityDuration: 86400
              frequency: 0
              purposes:
                - name: "profile_access"
                  version: "v1"
                  elements:
                    - name: "first_name"
                      approved: true
                      value: {}
                    - name: "last_name"
                      approved: true
                      value: {}
              attributes:
                department: "sales"
                region: "APAC"
              authorizations:
                - userId: "user1@example.com"
                  type: "authorisation"
                  status: "APPROVED"
                  resources:
                    accountIds: ["acc-123", "acc-456"]
        required: true
      responses:
        "200":
          description: OK. The full details of the requested consent are returned in the response body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentUpdateResponse"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to update the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consents/{consentId}/revoke:
    post:
      summary: Revoke a consent
      description: |
       Allows to revoke a consent. This action typically updates the consent status to a **revoke** type of status.

      operationId: consents-revoke-POST
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "The unique identifier for the organization (e.g., the bank) that this consent belongs to."
          schema:
            type: string
            example: "ORG-001"
        - name: consentId
          in: path
          description: The unique identifier of the consent to update.
          required: true
          schema:
            type: string
      requestBody:
        description: The payload containing the revocation data.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsentRevokePayload"
      responses:
        "200":
          description: Successfully revoked the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentRevokedResponse"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to create the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consents/{consentId}/authorizations:
    post:
      summary: Add an authorization resource to a consent
      description: Creates a new authorization resource and links it to the specified consent. This is typically done when a user interacts with the consent (e.g., at the start of the authorization flow).
      operationId: consents-authorizations-POST
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "Organisation ID."
          schema:
            type: string
            example: "ORG-001"
        - name: consentId
          in: path
          description: The unique identifier of the consent.
          required: true
          schema:
            type: string
      requestBody:
        description: Details of the authorization resource to be created.
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AuthorizationResourceRequestBody"
        required: true
      responses:
        '200':
          description: OK. Returns the details of the authorization resource.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConsentAuthorizationResource"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to create the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
    get:
      summary: Retrieve all authorization resources for a consent
      description: Retrieves a list of all authorization resources associated with a specific consent.
      operationId: consentAuthorizationGet
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "Organisation ID."
          schema:
            type: string
            example: "ORG-001"
        - name: consentId
          in: path
          description: The unique identifier of the consent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK. Returns an array of authorization resources.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ConsentAuthorizationResource"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to create the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consents/{consentId}/authorizations/{authorizationId}:
    get:
      summary: Retrieve a specific authorization resource
      description: Retrieves the details of a specific authorization resource linked to a given consent.
      operationId: consentAuthorizationIdGet
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "Organisation ID."
          schema:
            type: string
        - name: consentId
          in: path
          description: The unique identifier of the consent.
          required: true
          schema:
            type: string
        - name: authorizationId
          in: path
          description: The unique identifier of the authorization resource.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK. Returns the details of the authorization resource.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConsentAuthorizationResource"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to create the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
    put:
      summary: Update an authorization resource
      description: Updates the details (e.g., status) of a specific authorization resource associated with the given consent.
      operationId: consentAuthorizationIdPut
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "Organisation ID."
          schema:
            type: string
            example: "ORG-001"
        - name: consentId
          in: path
          description: The unique identifier of the consent.
          required: true
          schema:
            type: string
        - name: authorizationId
          in: path
          description: The unique identifier of the authorization resource to update.
          required: true
          schema:
            type: string
      requestBody:
        description: The updated details for the authorization resource.
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AuthorizationResourceRequestBody"
        required: true
      responses:
        '200':
          description: OK. Returns the details of the authorization resource.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConsentAuthorizationResource"
        "400":
          description: Bad Request. The request was malformed. This could be due to missing required headers or an invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server while trying to create the consent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consents/validate:
    post:
      summary: Validate a consent for a specific action
      description: |
        Validates whether a consent is valid and active for a specific user action or API request.

        This endpoint checks:
        - If the consent exists and belongs to the specified user
        - If the consent status is active (AUTHORIZED, ACTIVE, etc.)
        - If the consent has not expired based on expirationTime
        - If all mandatory elements within the purposes are approved (approved: true)

        If the consent has expired, the endpoint automatically updates the consent status to EXPIRED.
        If mandatory elements are not approved, validation returns false.

        **Response includes enriched consent information:**
        - Complete consent details with all fields
        - Consent elements enriched with type, description, and properties from element definitions

        **Note:** All responses return HTTP 200. Check the `isValid` field and `httpCode` in the response body to determine the actual validation result.
      operationId: consents-validate-POST
      tags:
        - Consents
      parameters:
        - in: header
          name: org-id
          required: true
          description: "The unique identifier for the organization."
          schema:
            type: string
            example: "ORG-001"
      requestBody:
        description: The validation request containing consent details and the action being validated.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateRequest"
            example:
              consentId: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: |
            Validation completed. Check the `isValid` field in the response body.
            - If `isValid: true`, the consent is valid for the requested action
            - If `isValid: false`, check `errorCode`, `errorMessage`, and `httpCode` for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateResponse"
              example:
                isValid: true
                consentInformation:
                  id: "123e4567-e89b-12d3-a456-426614174000"
                  type: "accounts"
                  groupId: "group-123"
                  status: "ACTIVE"
                  createdTime: 1702800000000
                  updatedTime: 1702800000000
                  expirationTime: 1734422400000
                  recurringIndicator: true
                  frequency: 10
                  dataAccessValidityDuration: 86400
                  purposes:
                    - purposeId: "550e8400-e29b-41d4-a716-446655440000"
                      name: "marketing_communication_preferences"
                      version: "v1"
                      displayName: "Marketing Communication Preferences"
                      properties:
                        category: "marketing"
                      elements:
                        - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                          name: "first_name"
                          namespace: "personal"
                          version: "v1"
                          value: {}
                          approved: true
                          mandatory: true
                          type: "basic"
                          description: "Allows access to the user's first name"
                          properties:
                            jsonPath: "$.personal.firstName"
                            resourcePath: "/user/{nic}"
                  attributes:
                    department: "sales"
                    region: "APAC"
                  authorizations:
                    - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      userId: "user1@example.com"
                      type: "authorisation"
                      status: "APPROVED"
                      updatedTime: 1702800000000
                      resources:
                        accountIds: ["acc-123", "acc-456"]
        "400":
          description: Bad Request - Invalid request body or missing required fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "BAD_REQUEST"
                message: "Invalid request"
                description: "Missing required field: consentId"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-elements:
    post:
      summary: Create one or more consent elements
      description: |
        Creates one or more consent elements in a single request. Supports batch creation by accepting
        an array of element definitions.

        When creating a consent, a value can be provided for each consent element. Based on the value type,
        consent elements have three types:
        - **basic**: Element value is treated as a simple string with no structural validation.
        - **json**: Element value is a JSON string, validated against the provided json element schema at consent creation time.
        - **xml**: Element value is an XML string, validated against the provided xml element schema at consent creation time.

        **Validation Rules:**
        - Name is required and must not exceed 255 characters
        - The combination of `name` + `namespace` must be unique within the organization
        - Type is required and must be one of: `basic`, `json`, `xml`
        - At least one element must be provided in the request array
      operationId: createConsentElements
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization that owns these elements
          schema:
            type: string
            example: "ORG-001"
      requestBody:
        description: Array of consent elements to create
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/ConsentElementCreateRequest"
            examples:
              basicElement:
                summary: Create a basic type element (namespace omitted — uses "default")
                value:
                  - name: "license_read"
                    type: "basic"
                    displayName: "License Read"
                    description: "Allows read access to license API endpoints"
                    properties:
                      value: "license:read"
                      resourcePath: "/api/license/{id}"
              jsonElement:
                summary: Create a json type element with schema validation
                value:
                  - name: "account_details"
                    type: "json"
                    displayName: "Account Details"
                    description: "Structured account information with JSON schema validation"
                    schema: '{"type":"object","properties":{"accountId":{"type":"string"},"balance":{"type":"number"}},"required":["accountId"]}'
                    properties:
                      resourcePath: "/accounts/{accountId}"
                      jsonPath: "$.account"
              xmlElement:
                summary: Create an xml type element with schema validation
                value:
                  - name: "patient_record_xml"
                    type: "xml"
                    displayName: "Patient Record (XML)"
                    description: "Patient record data validated against XML schema"
                    schema: '<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"><xs:element name="patient"><xs:complexType><xs:sequence><xs:element name="patientId" type="xs:string"/></xs:sequence></xs:complexType></xs:element></xs:schema>'
                    properties:
                      resourcePath: "/Patient/{patientId}"
                      xPath: "/patient/patientId"
              batchElements:
                summary: Create multiple elements in one batch (with explicit namespaces)
                value:
                  - name: "first_name"
                    namespace: "personal"
                    type: "basic"
                    displayName: "First Name"
                    description: "Access to the user's first name"
                    properties:
                      resourcePath: "/Patient/{firstName}"
                      jsonPath: "$.patient.firstName"
                  - name: "patient_record"
                    namespace: "healthcare"
                    type: "json"
                    displayName: "Patient Record"
                    description: "Full patient record with JSON schema validation"
                    schema: '{"type":"object","properties":{"patientId":{"type":"string"},"dob":{"type":"string","format":"date"}},"required":["patientId"]}'
                    properties:
                      resourcePath: "/Patient/{patientId}"
                      jsonPath: "$.patient"
      responses:
        "200":
          description: |
            Bulk creation processed. Check each item's `status` field — `SUCCESS` or `FAILED`.
            Valid items are batch-inserted; per-item validation errors do not prevent other items from being created.
            See `metadata` for a summary of how many succeeded and failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentElementBulkCreateResponse"
              examples:
                partialSuccess:
                  summary: Batch with one success and one failure
                  value:
                    metadata:
                      traceId: "4f9c2d7a-8b1e-4f9c-2d7a-8b1e4f9c2d7a"
                      total: 2
                      succeeded: 1
                      failed: 1
                    results:
                      - index: 0
                        status: "SUCCESS"
                        data:
                          elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                          name: "license_read"
                          namespace: "licensing"
                          type: "basic"
                          version: "v1"
                          displayName: "License Read"
                          description: "Allows read access to license API endpoints"
                          properties:
                            value: "license:read"
                            resourcePath: "/api/license/{id}"
                          createdTime: 1742860800000
                      - index: 1
                        status: "FAILED"
                        error:
                          code: "CONFLICT"
                          message: "Element already exists"
                          description: "Element name 'user_email' already exists in namespace 'personal'"
        "400":
          description: Bad Request — invalid top-level request (e.g. malformed JSON, empty array)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              examples:
                emptyArray:
                  summary: Empty array provided
                  value:
                    code: "BAD_REQUEST"
                    message: "Empty request"
                    description: "At least one element must be provided"
                    traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error — batch persistence failed after successful validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred while persisting elements"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
    get:
      summary: List all consent elements
      description: |
        Returns a paginated list of consent elements for the organization.

        By default (`details=false`), each item includes the immutable fields (`elementId`, `name`, `namespace`, `type`, `createdTime`), the latest `version` number, and the latest version's `displayName` and `description`.
        Set `details=true` to also include the full version content (schema, properties).

        Use `name`, `namespace`, or `type` to filter results. If `version` is specified, at least one of `name` or `namespace` must also be provided.
      operationId: listConsentElements
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: name
          in: query
          description: Filter elements by name (partial match, case-insensitive search)
          required: false
          schema:
            type: string
            example: "account"
        - name: namespace
          in: query
          description: Filter elements by namespace
          required: false
          schema:
            type: string
            example: "healthcare"
        - name: type
          in: query
          description: Filter elements by type
          required: false
          schema:
            type: string
            enum: [basic, json, xml]
            example: "basic"
        - name: version
          in: query
          description: |
            Filter by a specific version (e.g. `v2`). When provided, returns content of that
            version instead of the latest. Requires at least one of `name` or `namespace`.
          required: false
          schema:
            type: string
            example: "v2"
        - name: details
          in: query
          description: |
            When `true`, each element in the response also includes the full version content (schema, properties).
            `displayName` and `description` are always present regardless of this flag.
          required: false
          schema:
            type: boolean
            default: false
            example: true
        - name: limit
          in: query
          description: The maximum number of results to return in a single page. Used for pagination.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 100
            example: 10
        - name: offset
          in: query
          description: The number of results to skip. Used for pagination.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
            example: 0
      responses:
        "200":
          description: |
            Successfully retrieved consent elements.
            Shape of each item depends on `details` parameter — see `ConsentElementSummaryResponse` (default)
            and `ConsentElementVersionResponse` (when `details=true`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentElementListResponse"
              examples:
                summary:
                  summary: Default response (details=false)
                  value:
                    data:
                      - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "first_name"
                        namespace: "personal"
                        type: "basic"
                        version: "v3"
                        displayName: "First Name"
                        description: "Access to the user's first name"
                        createdTime: 1736467200000
                      - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                        name: "account_details"
                        namespace: "banking"
                        type: "json"
                        version: "v2"
                        displayName: "Account Details"
                        description: "Structured account information with JSON schema validation"
                        createdTime: 1738368000000
                    metadata:
                      total: 2
                      offset: 0
                      count: 2
                      limit: 100
                enriched:
                  summary: Detailed response (details=true)
                  value:
                    data:
                      - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "first_name"
                        namespace: "personal"
                        type: "basic"
                        version: "v3"
                        displayName: "First Name"
                        description: "User's first name"
                        properties:
                          resourcePath: "/Patient/{firstName}"
                          jsonPath: "$.patient.firstName"
                        createdTime: 1736467200000
                      - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                        name: "account_details"
                        namespace: "banking"
                        type: "json"
                        version: "v2"
                        displayName: "Account Details"
                        description: "Bank account information"
                        schema: '{"type":"object"}'
                        properties:
                          resourcePath: "/accounts/{accountId}"
                          jsonPath: "$.account"
                        createdTime: 1738368000000
                    metadata:
                      total: 2
                      offset: 0
                      count: 2
                      limit: 100
        "400":
          description: Bad Request — `version` provided without `name` or `namespace`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INVALID_REQUEST"
                message: "Invalid query parameters"
                description: "The 'version' parameter requires at least one of 'name' or 'namespace' to be specified"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Internal server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-elements/{elementId}:
    get:
      summary: Get consent element
      description: |
        Retrieves a consent element including the full content of its latest version
        (type, displayName, description, schema, properties).
      operationId: getConsentElement
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: elementId
          in: path
          required: true
          description: The unique identifier of the consent element
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "200":
          description: Successfully retrieved consent element
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentElementVersionResponse"
              example:
                elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "first_name"
                namespace: "personal"
                version: "v3"
                type: "basic"
                displayName: "First Name"
                description: "Allows access to the user's first name"
                createdTime: 1736467200000
        "404":
          description: Consent element not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Element not found"
                description: "Consent element does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-elements/{elementId}/versions:
    get:
      summary: List all versions of a consent element
      description: |
        Retrieves all versions of a consent element, ordered by version number (newest first).
      operationId: listElementVersions
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: elementId
          in: path
          required: true
          description: The unique identifier of the consent element
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "200":
          description: Successfully retrieved element versions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentElementVersionListResponse"
              example:
                elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "first_name"
                namespace: "personal"
                type: "basic"
                versions:
                  - version: "v2"
                    displayName: "First Name V2"
                    description: "Updated access to the user's first name"
                    properties:
                      resourcePath: "/Patient/{firstName}"
                      jsonPath: "$.patient.firstName"
                    createdTime: 1740787200000
                  - version: "v1"
                    displayName: "First Name"
                    description: "Allows access to the user's first name"
                    properties:
                      resourcePath: "/Patient/{firstName}"
                      jsonPath: "$.patient.firstName"
                    createdTime: 1736467200000
        "404":
          description: Consent element not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Element not found"
                description: "Consent element does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
    post:
      summary: Create a new version of a consent element
      description: |
        Creates a new version of an existing consent element. The version identifier is
        auto-incremented with a `v` prefix (e.g., `v2`, `v3`).

        **Immutable fields** (set at element creation, cannot change across versions):
        - `name`: The element identifier
        - `namespace`: The element namespace. If namespace was omitted at creation, it was set to `default`.
        - `type`: The element type (`basic`, `json`, `xml`). Fixed at creation time.

        **Mutable fields** (can be updated in each new version):
        - `displayName`, `description`, `schema`, `properties`

        **Schema requirement:**
        - `schema` field is required when the element type is `json` or `xml`
      operationId: createElementVersion
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: elementId
          in: path
          required: true
          description: The unique identifier of the consent element
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      requestBody:
        description: New version data for the consent element
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsentElementVersionCreateRequest"
            examples:
              basicType:
                summary: Create new version of a basic type element (all fields)
                value:
                  displayName: "First Name V2"
                  description: "Updated access to the user's first name with additional path mapping"
                  properties:
                    resourcePath: "/Patient/{firstName}"
                    jsonPath: "$.patient.firstName"
                    xPath: "/Patient/firstName"
              jsonType:
                summary: Create new version of a json type element (all fields)
                value:
                  displayName: "Account Details V2"
                  description: "Updated JSON schema to include account balance and currency fields"
                  schema: '{"type":"object","properties":{"accountId":{"type":"string"},"balance":{"type":"number"},"currency":{"type":"string"}},"required":["accountId"]}'
                  properties:
                    resourcePath: "/accounts/{accountId}"
                    jsonPath: "$.account"
              xmlType:
                summary: Create new version of an xml type element (all fields)
                value:
                  displayName: "Patient Record XML V2"
                  description: "Updated XML schema to include date of birth field"
                  schema: '<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"><xs:element name="patient"><xs:complexType><xs:sequence><xs:element name="patientId" type="xs:string"/><xs:element name="dob" type="xs:date"/></xs:sequence></xs:complexType></xs:element></xs:schema>'
                  properties:
                    resourcePath: "/Patient/{patientId}"
                    xPath: "/patient/patientId"
      responses:
        "201":
          description: Successfully created new version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentElementVersionResponse"
              examples:
                basicVersion:
                  summary: Created new version of a basic type element
                  value:
                    elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    name: "first_name"
                    namespace: "personal"
                    version: "v2"
                    type: "basic"
                    displayName: "First Name V2"
                    description: "Updated access to the user's first name with additional path mapping"
                    properties:
                      resourcePath: "/Patient/{firstName}"
                      jsonPath: "$.patient.firstName"
                      xPath: "/Patient/firstName"
                    createdTime: 1740787200000
                jsonVersion:
                  summary: Created new version of a json type element
                  value:
                    elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                    name: "account_details"
                    namespace: "banking"
                    version: "v2"
                    type: "json"
                    displayName: "Account Details V2"
                    description: "Updated JSON schema to include account balance and currency fields"
                    schema: '{"type":"object","properties":{"accountId":{"type":"string"},"balance":{"type":"number"},"currency":{"type":"string"}},"required":["accountId"]}'
                    properties:
                      resourcePath: "/accounts/{accountId}"
                      jsonPath: "$.account"
                    createdTime: 1740787200000
        "400":
          description: Bad Request - Invalid input or validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "BAD_REQUEST"
                message: "Invalid request"
                description: "Type must be one of: basic, json, xml"
                traceId: "20260107T123456Z-abc123"
        "404":
          description: Consent element not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Element not found"
                description: "Consent element does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-elements/{elementId}/versions/{version}:
    get:
      summary: Get a specific version of a consent element
      description: Retrieves the full detail of a specific version of a consent element.
      operationId: getElementVersion
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: elementId
          in: path
          required: true
          description: The unique identifier of the consent element
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: version
          in: path
          required: true
          description: The version identifier (e.g., v1, v2)
          schema:
            type: string
          example: "v1"
      responses:
        "200":
          description: Successfully retrieved consent element version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentElementVersionResponse"
              examples:
                basicVersion:
                  summary: Basic type element version
                  value:
                    elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    name: "first_name"
                    namespace: "personal"
                    version: "v1"
                    type: "basic"
                    displayName: "First Name"
                    description: "Allows access to the user's first name"
                    properties:
                      resourcePath: "/Patient/{firstName}"
                      jsonPath: "$.patient.firstName"
                      xPath: "/Patient/firstName"
                    createdTime: 1736467200000
                jsonVersion:
                  summary: json type element version
                  value:
                    elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                    name: "account_details"
                    namespace: "banking"
                    version: "v1"
                    type: "json"
                    displayName: "Account Details"
                    description: "Structured account information with JSON schema validation"
                    schema: '{"type":"object","properties":{"accountId":{"type":"string"},"balance":{"type":"number"}},"required":["accountId"]}'
                    properties:
                      resourcePath: "/accounts/{accountId}"
                      jsonPath: "$.account"
                    createdTime: 1736467200000
        "404":
          description: Element or version not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Version not found"
                description: "Consent element version does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
    delete:
      summary: Delete a specific version of a consent element
      description: |
        Deletes a specific version of a consent element.

        **Deletion Rules:**
        - Cannot delete a version if it is referenced by any purpose version, regardless of status (returns 409).
          All referencing purpose versions must be deleted before this version can be removed.
        - Deleting the only remaining version deletes the element itself.
      operationId: deleteElementVersion
      tags:
        - Consent Elements
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: elementId
          in: path
          required: true
          description: The unique identifier of the consent element
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: version
          in: path
          required: true
          description: The version identifier to delete (e.g., v1, v2)
          schema:
            type: string
          example: "v2"
      responses:
        "204":
          description: Successfully deleted consent element version
        "409":
          description: Conflict - Version is referenced by an existing purpose version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              examples:
                versionInUse:
                  summary: Version is referenced by a purpose version
                  value:
                    code: "CONFLICT"
                    message: "Version in use"
                    description: "Cannot delete version that is referenced by an existing purpose version"
                    traceId: "20260107T123456Z-abc123"
        "404":
          description: Element or version not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Version not found"
                description: "Consent element version does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-purposes:
    post:
      summary: Create a consent purpose
      description: |
        Creates a new consent purpose that organizes related consent elements together.

        **Purpose Ownership (group-id header):**
        - If the `group-id` header is **omitted or empty**, the purpose is an **org-level purpose** —
          its `groupId` is set to the `org-id` and it is available to all consents within the organization.
        - If `group-id` is **provided**, the purpose is a **group-specific purpose** owned by that group
          and can only be used by consents that belong to the same group.

        **Validation Rules:**
        - Purpose name is required and must be unique within the organization and group.
        - Purpose name must not exceed 255 characters.
        - Description is optional but must not exceed 1024 characters if provided.
        - At least one element version reference must be provided in the elements array.
        - All element references must specify an existing element by `name` (and optionally `namespace` and `version`).
        - Duplicate element references within the same purpose are not allowed.

        **Mandatory Flag:**
        The `mandatory` flag on each element indicates whether that element must be
        approved for the consent to be valid. This provides fine-grained control over
        which elements are essential vs. optional within the purpose.
      operationId: createPurpose
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization that owns this purpose
          schema:
            type: string
            example: "ORG-001"
        - in: header
          name: group-id
          required: false
          description: |
            The group this purpose belongs to. When omitted, the purpose is created as an
            org-level purpose (groupId is set to the org-id) and is available to all consents
            within the organization.
          schema:
            type: string
            example: "group-001"
      requestBody:
        description: Purpose definition
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PurposeCreateRequest"
            examples:
              marketingPurpose:
                summary: Marketing communication preferences purpose
                value:
                  name: "marketing_communication_preferences_purpose"
                  displayName: "Marketing Communication Preferences"
                  description: "User preferences related to marketing communications"
                  properties:
                    category: "marketing"
                    region: "global"
                  elements:
                    - name: "user_email"
                      namespace: "personal"
                      version: "v1"
                      mandatory: true
                    - name: "user_mobile"
                      namespace: "personal"
                      version: "v2"
                      mandatory: false
                    - name: "user_address"
                      namespace: "personal"
                      version: "v1"
                      mandatory: false
              govDataAccessPurpose:
                summary: Government data access purpose
                value:
                  name: "gov_data_access_purpose_attribute"
                  displayName: "Government Data Access"
                  description: "User consent to access user data in government portal"
                  properties:
                    sector: "government"
                  elements:
                    - name: "patient_name"
                      namespace: "medical"
                      version: "v1"
                      mandatory: false
                    - name: "medical_history"
                      namespace: "medical"
                      version: "v1"
                      mandatory: false
                    - name: "medical_record_id"
                      namespace: "medical"
                      version: "v1"
                      mandatory: true
      responses:
        "201":
          description: Successfully created purpose
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentPurposeCreateResponse"
              examples:
                marketingPurpose:
                  summary: Marketing purpose created
                  value:
                    purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    name: "marketing_communication_preferences_purpose"
                    groupId: "group-001"
                    version: "v1"
                    displayName: "Marketing Communication Preferences"
                    description: "User preferences related to marketing communications"
                    properties:
                      category: "marketing"
                      region: "global"
                    elements:
                      - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "user_email"
                        namespace: "personal"
                        version: "v1"
                        mandatory: true
                      - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                        name: "user_mobile"
                        namespace: "personal"
                        version: "v2"
                        mandatory: false
                    createdTime: 1742860800000
        "400":
          description: Bad Request - Invalid input or validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              examples:
                missingName:
                  summary: Missing required name field
                  value:
                    code: "BAD_REQUEST"
                    message: "Invalid request body"
                    description: "Name field is required"
                    traceId: "20260107T123456Z-abc123"
                duplicateName:
                  summary: Purpose name already exists
                  value:
                    code: "CONFLICT"
                    message: "Purpose already exists"
                    description: "Purpose name already exists"
                    traceId: "20260107T123456Z-abc123"
                emptyElements:
                  summary: No elements provided
                  value:
                    code: "BAD_REQUEST"
                    message: "Invalid request"
                    description: "At least one element must be provided"
                    traceId: "20260107T123456Z-abc123"
                elementNotFound:
                  summary: Referenced element doesn't exist
                  value:
                    code: "BAD_REQUEST"
                    message: "Invalid element reference"
                    description: "Element does not exist in organization"
                    traceId: "20260107T123456Z-abc123"
                duplicateElementInPurpose:
                  summary: Duplicate element in purpose
                  value:
                    code: "BAD_REQUEST"
                    message: "Invalid request"
                    description: "Duplicate element in purpose"
                    traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
    get:
      summary: List all purposes
      description: |
        Returns a paginated list of consent purposes for the organization.
        By default (`details=false`), each item includes the immutable fields (`purposeId`, `name`, `groupId`, `createdTime`), the latest `version` number, and the latest version's `displayName` and `description`.
        Set `details=true` to also include full version content (properties, elements).
        Use `purposeName`, `purposeVersion`, `elementName`, `elementNamespace`, `elementVersion`, or `groupIds` to filter results. If `purposeVersion` is specified, `purposeName` must also be provided. If `elementVersion` is specified, at least one of `elementName` or `elementNamespace` must also be provided.
      operationId: listPurposes
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: purposeName
          in: query
          required: false
          description: Filter by purpose name (partial match, case-insensitive)
          schema:
            type: string
          example: "marketing_communication_preferences"
        - name: purposeVersion
          in: query
          required: false
          description: |
            Filter by purpose version (e.g. "v2"). Requires purposeName to also be specified.
            Returns the purpose at that specific version instead of the latest.
          schema:
            type: string
          example: "v2"
        - name: elementName
          in: query
          required: false
          description: Filter by element name — returns purposes that contain this element
          schema:
            type: string
          example: "user_email"
        - name: elementNamespace
          in: query
          required: false
          description: Filter by element namespace — used together with elementName
          schema:
            type: string
          example: "personal"
        - name: elementVersion
          in: query
          required: false
          description: |
            Filter by a specific element version (e.g. "v2"). Requires at least one of elementName or elementNamespace to also be specified.
          schema:
            type: string
          example: "v2"
        - name: groupIds
          in: query
          required: false
          description: Comma-separated list of group IDs to filter purposes by
          schema:
            type: string
          example: "GROUP-123,GROUP-456"
        - name: details
          in: query
          required: false
          description: When `true`, each purpose in the response also includes full version content (properties, elements). `displayName` and `description` are always present regardless of this flag.
          schema:
            type: boolean
            default: false
          example: true
        - name: limit
          in: query
          description: Maximum number of results to return (default 10, max 100)
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 1
            maximum: 100
          example: 10
        - name: offset
          in: query
          description: Number of results to skip (for pagination)
          schema:
            type: integer
            format: int32
            default: 0
            minimum: 0
          example: 0
      responses:
        "200":
          description: Successfully retrieved purposes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PurposeListResponse"
              examples:
                summaryList:
                  summary: Default summary list (details=false)
                  value:
                    data:
                      - purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "marketing_communication_preferences_purpose"
                        groupId: "group-001"
                        version: "v3"
                        displayName: "Marketing Communication Preferences"
                        description: "User preferences related to marketing communications"
                        createdTime: 1736467200000
                      - purposeId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                        name: "account_access_permissions_purpose"
                        groupId: "group-001"
                        version: "v1"
                        displayName: "Account Access Permissions"
                        description: "Permissions for accessing account data"
                        createdTime: 1739577600000
                    metadata:
                      total: 2
                      offset: 0
                      count: 2
                      limit: 10
                detailedList:
                  summary: Detailed list (details=true)
                  value:
                    data:
                      - purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "marketing_communication_preferences_purpose"
                        groupId: "group-001"
                        version: "v3"
                        displayName: "Marketing Communication Preferences"
                        description: "User preferences related to marketing communications"
                        properties:
                          category: "marketing"
                          region: "global"
                        elements:
                          - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                            name: "user_email"
                            namespace: "personal"
                            version: "v1"
                            mandatory: true
                          - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                            name: "user_mobile"
                            namespace: "personal"
                            version: "v2"
                            mandatory: false
                        createdTime: 1736467200000
                    metadata:
                      total: 1
                      offset: 0
                      count: 1
                      limit: 10
                emptyResult:
                  summary: No purposes found
                  value:
                    data: []
                    metadata:
                      total: 0
                      offset: 0
                      count: 0
                      limit: 10
        "400":
          description: Bad Request - Invalid query parameters (e.g. purposeVersion provided without name)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "BAD_REQUEST"
                message: "Invalid query parameters"
                description: "purposeVersion requires purposeName to also be specified"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
      security:
        - basicAuth: []
  /consent-purposes/{purposeId}:
    get:
      summary: Get a consent purpose
      description: |
        Retrieves the full content of the latest version of a consent purpose,
        including displayName, description, properties, and element references.
      operationId: getPurposeById
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: purposeId
          in: path
          required: true
          description: The unique identifier of the purpose
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "200":
          description: Successfully retrieved purpose
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentPurposeVersionResponse"
              example:
                purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "marketing_communication_preferences_purpose"
                groupId: "group-001"
                version: "v3"
                displayName: "Marketing Communication Preferences"
                description: "User preferences related to marketing communications"
                properties:
                  category: "marketing"
                  region: "global"
                elements:
                  - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    name: "user_email"
                    namespace: "personal"
                    version: "v1"
                    mandatory: true
                  - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                    name: "user_mobile"
                    namespace: "personal"
                    version: "v2"
                    mandatory: false
                  - elementId: "c3d4e5f6-a7b8-9012-cdef-123456789012"
                    name: "user_address"
                    namespace: "personal"
                    version: "v1"
                    mandatory: false
                createdTime: 1736467200000
        "404":
          description: Purpose not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Purpose not found"
                description: "Purpose does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-purposes/{purposeId}/versions:
    get:
      summary: List all versions of a consent purpose
      description: |
        Retrieves all versions of a consent purpose, ordered by version number (newest first).
      operationId: listPurposeVersions
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: purposeId
          in: path
          required: true
          description: The unique identifier of the consent purpose
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "200":
          description: Successfully retrieved purpose versions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentPurposeVersionListResponse"
              example:
                purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "marketing_communication_preferences"
                groupId: "group-001"
                versions:
                  - version: "v2"
                    displayName: "Marketing Communication Preferences V2"
                    description: "Updated user preferences for marketing communications"
                    properties:
                      category: "marketing"
                      region: "global"
                    elements:
                      - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "user_email"
                        namespace: "personal"
                        version: "v1"
                        mandatory: true
                      - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                        name: "user_mobile"
                        namespace: "personal"
                        version: "v2"
                        mandatory: false
                      - elementId: "c3d4e5f6-a7b8-9012-cdef-123456789012"
                        name: "user_address"
                        namespace: "personal"
                        version: "v1"
                        mandatory: false
                    createdTime: 1740787200000
                  - version: "v1"
                    displayName: "Marketing Communication Preferences"
                    description: "User preferences related to marketing communications"
                    properties:
                      category: "marketing"
                      region: "APAC"
                    elements:
                      - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        name: "user_email"
                        namespace: "personal"
                        version: "v1"
                        mandatory: true
                      - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                        name: "user_mobile"
                        namespace: "personal"
                        version: "v1"
                        mandatory: false
                    createdTime: 1736467200000
        "404":
          description: Consent purpose not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Purpose not found"
                description: "Consent purpose does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
    post:
      summary: Create a new version of a consent purpose
      description: |
        Creates a new version of an existing consent purpose. The version number is auto-incremented.

        Versions are **immutable** — once created, the element references of a version cannot be changed.
        To update a purpose's elements, create a new version instead.

        **Validation Rules:**
        - Purpose with the specified ID must exist
        - At least one element reference must be provided
        - Each element reference must specify `name` of an existing element version; `namespace` and `version` are optional
        - Duplicate element references within the same purpose version are not allowed
      operationId: createPurposeVersion
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: purposeId
          in: path
          required: true
          description: The unique identifier of the consent purpose
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      requestBody:
        description: New version data for the consent purpose
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsentPurposeVersionCreateRequest"
            example:
              displayName: "Medical Data Access V2"
              description: "Updated access to basic medical record fields"
              properties:
                specialization: "general"
              elements:
                - name: "patient_name"
                  namespace: "medical"
                  version: "v1"
                  mandatory: true
                - name: "medical_history"
                  namespace: "medical"
                  version: "v2"
                  mandatory: false
      responses:
        "201":
          description: Successfully created new purpose version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentPurposeVersionResponse"
              example:
                purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "medical_data_access"
                groupId: "group-001"
                version: "v2"
                displayName: "Medical Data Access V2"
                description: "Updated access to basic medical record fields"
                properties:
                  specialization: "general"
                elements:
                  - elementId: "d4e5f6a7-b8c9-0123-defa-234567890123"
                    name: "patient_name"
                    namespace: "medical"
                    version: "v1"
                    mandatory: true
                  - elementId: "e5f6a7b8-c9d0-1234-efab-345678901234"
                    name: "medical_history"
                    namespace: "medical"
                    version: "v2"
                    mandatory: false
                createdTime: 1740787200000
        "400":
          description: Bad Request - Invalid input or validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              examples:
                emptyElements:
                  summary: No elements provided
                  value:
                    code: "BAD_REQUEST"
                    message: "Invalid request"
                    description: "At least one element must be provided"
                    traceId: "20260107T123456Z-abc123"
                elementVersionNotFound:
                  summary: Referenced element version does not exist
                  value:
                    code: "BAD_REQUEST"
                    message: "Invalid element reference"
                    description: "Element version does not exist in organization"
                    traceId: "20260107T123456Z-abc123"
        "404":
          description: Consent purpose not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Purpose not found"
                description: "Consent purpose does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
  /consent-purposes/{purposeId}/versions/{version}:
    get:
      summary: Get a specific version of a consent purpose
      description: Retrieves the full detail of a specific version of a consent purpose, including all element version references.
      operationId: getPurposeVersion
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: purposeId
          in: path
          required: true
          description: The unique identifier of the consent purpose
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: version
          in: path
          required: true
          description: The version identifier (e.g., v1, v2)
          schema:
            type: string
          example: "v1"
      responses:
        "200":
          description: Successfully retrieved purpose version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentPurposeVersionResponse"
              example:
                purposeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "medical_data_access"
                groupId: "group-001"
                version: "v1"
                displayName: "Medical Data Access V1"
                description: "Access to basic medical record fields"
                properties:
                  specialization: "general"
                elements:
                  - elementId: "d4e5f6a7-b8c9-0123-defa-234567890123"
                    name: "patient_name"
                    namespace: "medical"
                    version: "v1"
                    mandatory: true
                  - elementId: "e5f6a7b8-c9d0-1234-efab-345678901234"
                    name: "medical_history"
                    namespace: "medical"
                    version: "v1"
                    mandatory: false
                createdTime: 1736467200000
        "404":
          description: Purpose or version not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Version not found"
                description: "Purpose version does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
    delete:
      summary: Delete a specific version of a consent purpose
      description: |
        Deletes a specific version of a consent purpose.

        **Deletion Rules:**
        - Cannot delete a version if it is currently bound to any consent (returns 409).
        - Deleting the only remaining version deletes the purpose itself.
      operationId: deletePurposeVersion
      tags:
        - Consent Purposes
      parameters:
        - in: header
          name: org-id
          required: true
          description: The unique identifier for the organization
          schema:
            type: string
            example: "ORG-001"
        - name: purposeId
          in: path
          required: true
          description: The unique identifier of the consent purpose
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: version
          in: path
          required: true
          description: The version identifier to delete (e.g., v1, v2)
          schema:
            type: string
          example: "v2"
      responses:
        "204":
          description: Successfully deleted purpose version
        "409":
          description: Conflict - Version is bound to an active consent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              examples:
                versionInUse:
                  summary: Version is bound to active consents
                  value:
                    code: "CONFLICT"
                    message: "Version in use"
                    description: "Cannot delete version that is referenced by active consents"
                    traceId: "20260107T123456Z-abc123"
        "404":
          description: Purpose or version not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "NOT_FOUND"
                message: "Version not found"
                description: "Purpose version does not exist"
                traceId: "20260107T123456Z-abc123"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentErrorCommon"
              example:
                code: "INTERNAL_ERROR"
                message: "Server error"
                description: "An unexpected error occurred"
                traceId: "20260107T123456Z-abc123"
      security:
        - basicAuth: []
components:
  schemas:
    ConsentPurposeItem:
      type: object
      description: |
        Represents a purpose within a consent, containing multiple related consent elements
        with their approval states.

        **Purpose Validation:**
        The `name` must reference an existing purpose in the organization.
        Each element in the `elements` array is identified by `name` + `namespace` and must be part of the referenced purpose.

        **Usage:**
        Used in consent create/update requests and responses to organize consent elements into
        logical groupings (e.g., "marketing_communication_preferences_purpose").
      required:
        - name
      properties:
        name:
          type: string
          description: |
            The name of an existing purpose to include in this consent.
            Must match the name of a purpose that has been previously created in the organization.
          example: "marketing_communication_preferences"
        purposeId:
          type: string
          description: Unique identifier of the purpose. Present in responses; omitted in requests.
          example: "550e8400-e29b-41d4-a716-446655440000"
        version:
          type: string
          description: |
            The specific version of the purpose to bind this consent to (e.g., v1, v2).
            If not specified, the latest version is used.
          example: "v1"
        elements:
          type: array
          description: |
            Optional array of consent element approvals within this purpose.
            Each entry sets the approval state and optional value for a specific element.
            Any elements defined in the purpose but not listed here are automatically
            resolved with `approved: false`. If omitted entirely, all elements are
            resolved from the purpose definition with `approved: false`.
          items:
            $ref: "#/components/schemas/ConsentElementApprovalItem"
    ConsentElementApprovalItem:
      type: object
      description: |
        Represents a single consent element approval within a consent.
        Contains the element name, namespace, and whether the user has approved it.

        The combination of `name` + `namespace` uniquely identifies the element within the purpose.
        If `namespace` is not provided, the `default` namespace is used.

        **Note:** The mandatory flag is defined at the purpose level,
        not at the individual consent level.
      required:
        - name
        - approved
      properties:
        elementId:
          type: string
          description: Unique identifier of the consent element. Present in responses; omitted in requests.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: |
            The name of the consent element.
            Must match an existing element name and must be part of the parent purpose.
          example: "user_email"
        namespace:
          type: string
          description: |
            The namespace of the consent element.
            Combined with `name`, uniquely identifies the element within the organization.
            If not provided, the `default` namespace is used.
          example: "personal"
        approved:
          type: boolean
          description: |
            Indicates whether the user has approved this specific consent element for this consent.

            - `true`: User has granted consent for this element
            - `false`: User has declined consent for this element

            **Validation:** If the element is marked as mandatory in the purpose definition,
            this field should typically be true for the consent to be valid.
          example: true
        value:
          description: |
            Optional element-specific value - flexible type that can be:
            - string: Simple text value
            - object: Structured data
            - array: List of values

            This field is OPTIONAL and can be used to store additional context or data
            specific to this element within the consent. Some elements may require a value,
            while others may not.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
          example:
            scope: "read"
            permissions: ["email", "profile"]
    AuthorizationResourceRequestBody:
      type: object
      description: |
        Payload for creating or updating an authorization resource.

        **Authorization Type:**
        The `type` field is optional. When not provided, the server defaults to `"default"`.

        **Authorization Status/State:**
        The `status` field represents the authorization state which determines the consent status:
        - `approved` (default if not provided): Authorization is approved → consent will be "active"
        - `created`: Authorization is created but not yet approved → consent will be "created"
        - `rejected`: Authorization was rejected → consent will be "rejected"
        - Custom values: Will be resolved via extension point to one of the known consent statuses
      required:
        - userId
      properties:
        userId:
          description: The unique ID of the user who performed this authorization.
          type: string
          example: "admin@carbon.super"
        type:
          description: The type of authorization (e.g., 'authorisation', 're-authorisation'). Defaults to "default" when not provided.
          type: string
          example: "authorisation"
        status:
          description: |
            The current status/state of this specific authorization.

            Defaults to "APPROVED" if not provided. Known states:
            - `APPROVED`: Authorization approved (default) → consent becomes ACTIVE
            - `CREATED`: Authorization created but not yet approved → consent becomes CREATED
            - `REJECTED`: Authorization rejected → consent becomes REJECTED
            - Custom states: Resolved via extension point
          type: string
          example: "APPROVED"
          enum:
            - CREATED
            - APPROVED
            - REJECTED
        resources:
          description: |
            Flexible resources field that can contain any valid JSON structure.

            This field replaces the deprecated `approvedPurposeDetails` and can be used to store:
            - Account information
            - Payment details
            - Resource identifiers
            - Any other authorization-specific data

            The API validates that this is valid JSON but does not enforce a specific schema.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
          example:
            accountIds: ["123456", "789012"]
            permissions: ["read", "write"]
    ConsentRevokePayload:
      type: object
      description: The request body for revoking a consent.
      required:
        - actionBy
      properties:
        actionBy:
          description: Identifier of the user or system performing the revoke action.
          type: string
          example: "admin@wso2.com"
        revocationReason:
          description: The reason for revoking the consent.
          type: string
          example: "Admin revoke"
    ConsentCreatePayload:
      type: object
      description: |
        The request body for initiating a new consent.

        **Status Derivation:**
        The consent status is NOT provided in the request. Instead, it is automatically derived by the API based on the authorization states:
        - If any authorization has status REJECTED → consent status = REJECTED
        - If any authorization has status CREATED → consent status = CREATED
        - If all authorizations have status APPROVED (or empty/default) → consent status = ACTIVE
        - For custom authorization states → consent status is resolved via extension point (must return a known status)

        **Known Consent Statuses:**
        - `CREATED`: Consent is created but not yet approved
        - `ACTIVE`: Consent is approved and active
        - `REJECTED`: Consent was rejected
        - `REVOKED`: Consent was revoked
        - `EXPIRED`: Consent has expired
      required:
        - type
        - purposes
      properties:
        type:
          description: The type of consent (e.g., 'accounts', 'payments', 'marketing').
          type: string
          example: "marketing"
        expirationTime:
          description: |
            Unix timestamp when the consent expires. Set to 0 to indicate no expiration.
            Values less than 10^11 are interpreted as seconds and automatically converted to milliseconds.
            Values >= 10^11 are treated as already in milliseconds.
          type: integer
          format: int64
          example: 1766383796
        recurringIndicator:
          description: A boolean flag indicating if the consent is for a recurring payment or access.
          type: boolean
          example: true
        dataAccessValidityDuration:
          description: The duration for which data access is valid, in seconds. Optional field that specifies how long the consent allows access to user data.
          type: integer
          format: int64
          example: 0
        frequency:
          description: For recurring consents, this indicates the frequency (e.g., per day). '0' may indicate no limit.
          type: integer
          format: int32
          example: 0
        purposes:
          description: |
            Array of purposes for this consent (REQUIRED).

            Each purpose contains multiple consent elements with their approval states.
            At least one purpose must be provided.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ConsentPurposeItem"
        attributes:
          description: A key-value map of additional, non-standard attributes associated with the consent.
          type: object
          additionalProperties:
            type: string
          example:
            department: "sales"
            region: "APAC"
        authorizations:
          description: An array of authorization resources linked to this consent, detailing which users have acted upon it.
          type: array
          items:
            $ref: "#/components/schemas/ConsentAuthorizationCreatePayload"
    ConsentAuthorizationCreatePayload:
      type: object
      description: |
        Represents a detailed authorization object.

        **Authorization State:**
        The status field represents the authorization state which determines the consent status:
        - `APPROVED` (default if not provided): Authorization is approved → consent will be ACTIVE
        - `CREATED`: Authorization is created but not yet approved → consent will be CREATED
        - `REJECTED`: Authorization was rejected → consent will be REJECTED
        - Custom states: Will be resolved via extension point to determine final consent status
      required:
        - userId
      properties:
        userId:
          description: The unique ID of the user who performed this authorization.
          type: string
          example: "admin@carbon.super"
        type:
          description: The type of authorization (e.g., 'authorisation', 're-authorisation').
          type: string
          example: "authorisation"
        status:
          description: |
            The authorization state (defaults to APPROVED if not provided).
            Known states: APPROVED, CREATED, REJECTED.
            Custom states will be resolved via extension point.
          type: string
          example: "APPROVED"
          enum:
            - CREATED
            - APPROVED
            - REJECTED
        resources:
          description: |
            Flexible resources field that can contain any valid JSON structure.

            Can store account IDs, payment details, resource identifiers, or any
            other authorization-specific data. Validated as JSON but no schema enforced.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
          example:
            accountIds: ["123456", "789012"]
    ConsentAuthorizationCreateResponse:
      type: object
      description: Represents a detaild authorization object.
      required:
        - id
        - userId
        - type
        - updatedTime
      properties:
        id:
          description: Auth Id
          type: string
          example: "auth_id"
        userId:
          description: The unique ID of the user who performed this authorization.
          type: string
          example: "admin@carbon.super"
        type:
          description: The type of authorization (e.g., 'authorisation', 're-authorisation').
          type: string
          example: "authorisation"
        status:
          description: The current status of this specific authorization (e.g., 'created', 'approved', 'rejected').
          type: string
          example: "created"
        updatedTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this authorization was last updated.
          example: 1702800000000
        resources:
          description: Flexible resources field containing authorization-specific data as JSON.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
          example:
            accountIds: ["123456", "789012"]
    ConsentErrorCommon:
      type: object
      description: A standardized error response object.
      properties:
        code:
          description: Error code.
          type: string
        message:
          description: A short, human-readable summary of the problem.
          type: string
        description:
          description: A detailed explanation of the error.
          type: string
        traceId:
          description: TraceId
          type: string
    ConsentSearchResponse:
      type: object
      description: The response from a successful consent search query.
      properties:
        data:
          description: An array of detailed consent objects matching the search criteria.
          type: array
          items:
            $ref: "#/components/schemas/ConsentDetail"
        metadata:
          $ref: "#/components/schemas/ConsentSearchMetadata"
    ConsentUpdateRequest:
      type: object
      description: |
        Request body for updating a consent.

        **Status Derivation:**
        The consent status is NOT provided in the request. Instead, it is automatically derived by the API based on the authorization states:
        - If any authorization has status "rejected" → consent status = "rejected"
        - If any authorization has status "created" → consent status = "created"
        - If all authorizations have status "approved" (or empty/default) → consent status = "active"
        - For custom authorization states → consent status is resolved via extension point (must return a known status)

        **Purposes:**
        The purposes field is REQUIRED and will completely replace existing consent elements.
        The API always clears existing element mappings and creates new ones from the request.
      required:
        - purposes
        - type
      properties:
        type:
          description: The type of consent (e.g., 'accounts', 'payments', 'marketing').
          type: string
          example: "marketing"
        expirationTime:
          description: |
            Unix timestamp when the consent expires. Set to 0 to indicate no expiration.
            Values less than 10^11 are interpreted as seconds and automatically converted to milliseconds.
            Values >= 10^11 are treated as already in milliseconds.
          type: integer
          format: int64
          example: 1766383796
        recurringIndicator:
          description: A boolean flag indicating if the consent is for a recurring payment or access.
          type: boolean
          example: true
        dataAccessValidityDuration:
          description: The duration for which data access is valid, in seconds. Optional field that specifies how long the consent allows access to user data.
          type: integer
          format: int64
          example: 0
        frequency:
          description: For recurring consents, this indicates the frequency (e.g., per day). '0' may indicate no limit.
          type: integer
          format: int32
          example: 0
        purposes:
          description: |
            Array of purposes for this consent (REQUIRED).

            This field completely replaces existing consent elements. All existing element mappings
            will be cleared and new ones created from this array.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ConsentPurposeItem"
        attributes:
          description: A key-value map of additional, non-standard attributes associated with the consent.
          type: object
          additionalProperties:
            type: string
          example:
            department: "sales"
            region: "APAC"
        authorizations:
          description: An array of authorization resources linked to this consent, detailing which users have acted upon it.
          type: array
          items:
            $ref: "#/components/schemas/ConsentAuthorizationCreatePayload"
    ConsentUpdateResponse:
      type: object
      description: A generic success response for consent management operations that return consent details.
      required:
        - id
        - type
        - groupId
        - status
        - purposes
        - createdTime
        - updatedTime
      example:
        id: "123e4567-e89b-12d3-a456-426614174000"
        purposes:
          - purposeId: "550e8400-e29b-41d4-a716-446655440000"
            name: "marketing_communication_preferences"
            version: "v1"
            elements:
              - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "user_email"
                namespace: "personal"
                approved: true
                value: {}
              - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                name: "user_mobile"
                namespace: "personal"
                approved: true
                value: {}
        createdTime: 1702800000000
        updatedTime: 1702800000000
        groupId: "group-123"
        type: "marketing"
        status: "ACTIVE"
        frequency: 0
        expirationTime: 1766383796000
        recurringIndicator: true
        dataAccessValidityDuration: 0
        attributes:
          department: "marketing"
        authorizations:
          - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            userId: "user1@example.com"
            type: "authorisation"
            status: "APPROVED"
            updatedTime: 1702800000000
            resources:
              accountIds: ["acc-123", "acc-456"]
      properties:
        id:
          description: Consent Id
          type: string
          example: "consent_id"
        purposes:
          description: Array of purposes for this consent with their purposes and approval states.
          type: array
          items:
            $ref: "#/components/schemas/ConsentPurposeItem"
        createdTime:
          type: integer
          format: int64
          example: 1702800000000
        updatedTime:
          type: integer
          format: int64
          example: 1702800000000
        groupId:
          type: string
        type:
          description: The type of consent (e.g., 'accounts', 'payments').
          type: string
          example: "accounts"
        status:
          description: "The current status of the consent in its lifecycle. Valid values are: CREATED, ACTIVE, REJECTED, REVOKED, EXPIRED. Status is derived from authorization state - APPROVED authorization yields ACTIVE, CREATED authorization yields CREATED, REJECTED authorization yields REJECTED."
          type: string
          example: "ACTIVE"
        frequency:
          description: For recurring consents, this indicates the frequency (e.g., per day). '0' may indicate no limit.
          type: integer
          format: int32
          example: 0
        expirationTime:
          description: Unix timestamp (milliseconds) when the consent expires. Set to 0 to indicate no expiration.
          type: integer
          format: int64
          example: 0
        recurringIndicator:
          description: A boolean flag indicating if the consent is for a recurring payment or access.
          type: boolean
          example: false
        dataAccessValidityDuration:
          description: The duration for which data access is valid, in seconds. Optional field that specifies how long the consent allows access to user data.
          type: integer
          format: int64
          example: 86400
        attributes:
          description: A key-value map of additional, non-standard attributes associated with the consent.
          type: object
          additionalProperties:
            type: string
          example:
            department: "sales"
            region: "APAC"
        authorizations:
          description: An array of authorization resources linked to this consent, detailing which users have acted upon it.
          type: array
          items:
            $ref: "#/components/schemas/ConsentAuthorizationCreateResponse"
    ConsentRetrievalResponse:
      description: The response body returned after successfully initiating a new consent.
      example:
        id: "123e4567-e89b-12d3-a456-426614174000"
        purposes:
          - purposeId: "550e8400-e29b-41d4-a716-446655440000"
            name: "marketing_communication_preferences"
            version: "v1"
            elements:
              - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "user_email"
                namespace: "personal"
                approved: true
                value: {}
              - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                name: "user_mobile"
                namespace: "personal"
                approved: true
                value: {}
        createdTime: 1702800000000
        updatedTime: 1702800000000
        groupId: "group-123"
        type: "marketing"
        status: "ACTIVE"
        frequency: 0
        expirationTime: 1766383796000
        recurringIndicator: true
        dataAccessValidityDuration: 0
        attributes:
          department: "marketing"
        authorizations:
          - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            userId: "user1@example.com"
            type: "authorisation"
            status: "APPROVED"
            updatedTime: 1702800000000
            resources:
              accountIds: ["acc-123", "acc-456"]
      required:
        - id
        - type
        - groupId
        - status
        - purposes
        - createdTime
        - updatedTime
      properties:
        id:
          description: Consent Id
          type: string
          example: "consent_id"
        purposes:
          description: Array of purposes for this consent with their consent elements and approval states.
          type: array
          items:
            $ref: "#/components/schemas/ConsentPurposeItem"
        createdTime:
          type: integer
          format: int64
          example: 1702800000000
        updatedTime:
          type: integer
          format: int64
          example: 1702800000000
        groupId:
          type: string
        type:
          description: The type of consent (e.g., 'accounts', 'payments').
          type: string
          example: "accounts"
        status:
          description: The current status of the consent in its lifecycle. Valid values are 'created', 'active', 'rejected', 'revoked', 'expired'. Status is derived from authorization state - approved authorization yields 'active', created authorization yields 'created', rejected authorization yields 'rejected'.
          type: string
          example: "active"
        frequency:
          description: For recurring consents, this indicates the frequency (e.g., per day). '0' may indicate no limit.
          type: integer
          format: int32
          example: 0
        expirationTime:
          description: Unix timestamp (milliseconds) when the consent expires. Set to 0 to indicate no expiration.
          type: integer
          format: int64
          example: 0
        recurringIndicator:
          description: A boolean flag indicating if the consent is for a recurring payment or access.
          type: boolean
          example: false
        dataAccessValidityDuration:
          description: The duration for which data access is valid, in seconds. Optional field that specifies how long the consent allows access to user data.
          type: integer
          format: int64
          example: 86400

        attributes:
          description: A key-value map of additional, non-standard attributes associated with the consent.
          type: object
          additionalProperties:
            type: string
          example:
            department: "sales"
            region: "APAC"
        authorizations:
          description: An array of authorization resources linked to this consent, detailing which users have acted upon it.
          type: array
          items:
            $ref: "#/components/schemas/ConsentAuthorizationCreateResponse"
    ConsentRevokedResponse:
      type: object
      description: The response body returned after successfully revoking a consent.
      properties:
        actionTime:
          description: The Unix timestamp (in milliseconds) when the revocation occurred.
          type: integer
          format: int64
          example: 1758829540000
        actionBy:
          description: The user or system that performed the revoke action.
          type: string
          example: "admin@wso2.com"
        revocationReason:
          description: The reason provided for revoking the consent.
          type: string
          example: "Admin revoke"
    ConsentCreatedResponse:
      type: object
      description: The response body returned after successfully initiating a new consent.
      required:
        - id
        - type
        - groupId
        - status
        - purposes
        - createdTime
        - updatedTime
      example:
        id: "123e4567-e89b-12d3-a456-426614174000"
        purposes:
          - purposeId: "550e8400-e29b-41d4-a716-446655440000"
            name: "marketing_communication_preferences"
            version: "v1"
            elements:
              - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "user_email"
                namespace: "personal"
                approved: true
                value: {}
              - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                name: "user_mobile"
                namespace: "personal"
                approved: true
                value: {}
        createdTime: 1702800000000
        updatedTime: 1702800000000
        groupId: "group-123"
        type: "marketing"
        status: "ACTIVE"
        frequency: 0
        expirationTime: 1766383796000
        recurringIndicator: true
        dataAccessValidityDuration: 0
        attributes:
          department: "marketing"
        authorizations:
          - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            userId: "user1@example.com"
            type: "authorisation"
            status: "APPROVED"
            updatedTime: 1702800000000
            resources:
              accountIds: ["acc-123", "acc-456"]
      properties:
        id:
          description: Consent Id
          type: string
          example: "consent_id"
        purposes:
          description: Array of purposes for this consent with their purposes and approval states.
          type: array
          items:
            $ref: "#/components/schemas/ConsentPurposeItem"
        createdTime:
          type: integer
          format: int64
          example: 1702800000000
        updatedTime:
          type: integer
          format: int64
          example: 1702800000000
        groupId:
          type: string
        type:
          description: The type of consent (e.g., 'accounts', 'payments').
          type: string
          example: "accounts"
        status:
          description: "The current status of the consent in its lifecycle. Valid values are: CREATED, ACTIVE, REJECTED, REVOKED, EXPIRED. Status is derived from authorization state - APPROVED authorization yields ACTIVE, CREATED authorization yields CREATED, REJECTED authorization yields REJECTED."
          type: string
          example: "ACTIVE"
        frequency:
          description: For recurring consents, this indicates the frequency (e.g., per day). '0' may indicate no limit.
          type: integer
          format: int32
          example: 0
        expirationTime:
          description: Unix timestamp (milliseconds) when the consent expires. Set to 0 to indicate no expiration.
          type: integer
          format: int64
          example: 0
        recurringIndicator:
          description: A boolean flag indicating if the consent is for a recurring payment or access.
          type: boolean
          example: false
        dataAccessValidityDuration:
          description: The duration for which data access is valid, in seconds. Optional field that specifies how long the consent allows access to user data.
          type: integer
          format: int64
          example: 86400
        attributes:
          description: A key-value map of additional, non-standard attributes associated with the consent.
          type: object
          additionalProperties:
            type: string
          example:
            department: "sales"
            region: "APAC"
        authorizations:
          description: An array of authorization resources linked to this consent, detailing which users have acted upon it.
          type: array
          items:
            $ref: "#/components/schemas/ConsentAuthorizationCreateResponse"
    ConsentDetail:
      type: object
      description: A comprehensive object representing a single consent and all its associated data.
      required:
        - id
        - type
        - groupId
        - status
        - purposes
        - createdTime
        - updatedTime
      example:
        id: "123e4567-e89b-12d3-a456-426614174000"
        purposes:
          - purposeId: "550e8400-e29b-41d4-a716-446655440000"
            name: "marketing_communication_preferences"
            version: "v1"
            elements:
              - elementId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "user_email"
                namespace: "personal"
                approved: true
                value: {}
              - elementId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                name: "user_mobile"
                namespace: "personal"
                approved: true
                value: {}
        createdTime: 1702800000000
        updatedTime: 1702800000000
        groupId: "group-123"
        type: "marketing"
        status: "ACTIVE"
        frequency: 0
        expirationTime: 1766383796000
        recurringIndicator: true
        dataAccessValidityDuration: 0
        attributes:
          department: "marketing"
        authorizations:
          - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            userId: "user1@example.com"
            type: "authorisation"
            status: "APPROVED"
            updatedTime: 1702800000000
            resources:
              accountIds: ["acc-123", "acc-456"]
      properties:
        id:
          description: Consent Id
          type: string
          example: "consent_id"
        purposes:
          description: Array of purposes for this consent with their purposes and approval states.
          type: array
          items:
            $ref: "#/components/schemas/ConsentPurposeItem"
        createdTime:
          type: integer
          format: int64
          example: 1702800000000
        updatedTime:
          type: integer
          format: int64
          example: 1702800000000
        groupId:
          type: string
        type:
          description: The type of consent (e.g., 'accounts', 'payments', 'marketing').
          type: string
          example: "accounts"
        status:
          description: "The current status of the consent in its lifecycle. Valid values are: CREATED, ACTIVE, REJECTED, REVOKED, EXPIRED. Status is derived from authorization state - APPROVED authorization yields ACTIVE, CREATED authorization yields CREATED, REJECTED authorization yields REJECTED."
          type: string
          example: "ACTIVE"
        frequency:
          description: For recurring consents, this indicates the frequency (e.g., per day). '0' may indicate no limit.
          type: integer
          format: int32
          example: 0
        expirationTime:
          description: Unix timestamp (milliseconds) when the consent expires. Set to 0 to indicate no expiration.
          type: integer
          format: int64
          example: 0
        recurringIndicator:
          description: A boolean flag indicating if the consent is for a recurring payment or access.
          type: boolean
          example: false
        dataAccessValidityDuration:
          description: The duration for which data access is valid, in seconds. Optional field that specifies how long the consent allows access to user data.
          type: integer
          format: int64
          example: 86400
        attributes:
          description: A key-value map of additional, non-standard attributes associated with the consent.
          type: object
          additionalProperties:
            type: string
          example:
            department: "sales"
            region: "APAC"
        authorizations:
          description: An array of authorization resources linked to this consent, detailing which users have acted upon it.
          type: array
          items:
            $ref: "#/components/schemas/ConsentAuthorizationCreateResponse"
    ConsentSearchMetadata:
      type: object
      description: Pagination metadata returned with search results.
      properties:
        total:
          description: The total number of results available for the query, ignoring pagination.
          type: integer
          example: 100
        offset:
          description: The starting position of the returned result set.
          type: integer
          example: 0
        count:
          description: The number of results included in the current response (size of data array).
          type: integer
          example: 10
        limit:
          description: The maximum number of results requested per page.
          type: integer
          example: 10
    ConsentAuthorizationResource:
      type: object
      description: Represents a specific authorization action taken on a consent by a user.
      required:
        - id
        - userId
        - type
        - updatedTime
      properties:
        id:
          description: Auth Id
          type: string
          example: "auth_id"
        userId:
          description: The unique ID of the user who performed this authorization.
          type: string
          example: "admin@carbon.super"
        type:
          description: The type of authorization (e.g., 'authorisation', 're-authorisation').
          type: string
          example: "authorisation"
        status:
          description: The current status of this specific authorization (e.g., 'created', 'approved', 'rejected').
          type: string
          example: "created"
        updatedTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this authorization was last updated.
          example: 1702800000000
        resources:
          description: Flexible resources field containing authorization-specific data as JSON.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
          example:
            accountIds: ["123456", "789012"]
    ValidateRequest:
      type: object
      description: Request payload for validating a consent for a specific action.
      required:
        - consentId
      properties:
        consentId:
          description: The unique identifier of the consent to validate.
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
        userId:
          description: The unique identifier of the user performing the action (optional).
          type: string
          example: "user123"
        groupId:
          description: An identifier used to group related objects (optional).
          type: string
          example: "banking-app-001"
        headers:
          description: Optional headers from the actual API request being validated.
          type: object
          additionalProperties:
            type: string
        payload:
          description: Optional payload from the actual API request being validated.
          type: object
        electedResource:
          description: The resource the user is trying to access (optional).
          type: string
        resourceParams:
          description: Parameters describing the specific action being validated.
          type: object
          required:
            - resource
            - httpMethod
          properties:
            resource:
              description: The API resource path being accessed.
              type: string
              example: "/aisp/accounts/{AccountId}?queryParam=queryParamValue"
            httpMethod:
              description: The HTTP method of the request.
              type: string
              example: "GET"
            context:
              description: Additional context about the request.
              type: string
              example: "/open-banking/v3.1/aisp"
    ValidateResponse:
      type: object
      description: Response payload from consent validation.
      required:
        - isValid
      properties:
        isValid:
          description: Whether the consent is valid for the requested action.
          type: boolean
          example: true
        errorCode:
          description: HTTP status code if validation failed (e.g., 401, 404, 500).
          type: integer
          example: 401
        errorMessage:
          description: Error type/code if validation failed (e.g., "invalid_consent_status", "consent_expired", "consent_not_found").
          type: string
          example: "consent_expired"
        errorDescription:
          description: Human-readable detailed error description if validation failed.
          type: string
          example: "Consent has expired. Status updated to: EXPIRED"
        consentInformation:
          description: |
            Complete consent information.

            **Includes enriched consent element details:**
            - Each consent element includes type, description, and attributes from the purpose definition
            - This allows clients to understand what each purpose means without additional API calls

            Always present in the response, regardless of validation result.
          allOf:
            - $ref: "#/components/schemas/ValidateConsentAPIResponse"
    ValidateConsentAPIResponse:
      type: object
      description: Complete consent information returned in the validate response
      properties:
        id:
          type: string
          description: Unique identifier for the consent (UUID format)
          example: "123e4567-e89b-12d3-a456-426614174000"
        type:
          type: string
          description: The consent type (e.g., accounts, payments, etc.)
          example: "accounts"
        groupId:
          type: string
          description: The group ID associated with this consent
          example: "client-app-123"
        status:
          type: string
          description: Current status of the consent (CREATED, ACTIVE, EXPIRED, REVOKED, REJECTED, etc.)
          example: "ACTIVE"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when the consent was created.
          example: 1699564800000
        updatedTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when the consent was last updated.
          example: 1699651200000
        expirationTime:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (milliseconds) until which the consent is valid. If expired, status will be EXPIRED. Omitted from response when null.
          example: 1707340800000
        recurringIndicator:
          type: boolean
          nullable: true
          description: Indicates if the consent can be used repeatedly. Omitted from response when null.
          example: true
        frequency:
          type: integer
          nullable: true
          description: Number of times the consent can be used (if recurringIndicator is true). Omitted from response when null.
          example: 10
        dataAccessValidityDuration:
          type: integer
          format: int64
          nullable: true
          description: Duration in seconds for which data access is valid after each authorization. Omitted from response when null.
          example: 86400
        purposes:
          type: array
          description: |
            List of purposes containing consent elements with their approval state, mandatory flag, and **enriched details from purpose/element definitions**.
            Each purpose contains:
            - name: Name of the purpose
            - version: The specific version of the purpose bound to this consent
            - displayName: Human-readable display name of the purpose version
            - properties: Key-value properties of the purpose version
            - elements: Array of elements in this purpose

            Each element includes:
            - name: Element identifier
            - namespace: Element namespace (with name, uniquely identifies the element)
            - version: The specific version of the element bound to this consent purpose
            - value: User-provided value for this element (if any)
            - approved: Whether the user has approved this element (boolean, default false)
            - mandatory: Whether this element is mandatory (boolean) - indicates if approval is required
            - type: Element type from definition (basic, json, or xml)
            - description: Element description from definition
            - properties: Element properties from definition (e.g., schema, resourcePath, jsonPath)
          items:
            type: object
            required:
              - purposeId
              - name
              - version
              - elements
            properties:
              purposeId:
                type: string
                description: Unique identifier of the purpose
                example: "550e8400-e29b-41d4-a716-446655440000"
              name:
                type: string
                description: Name of the purpose
                example: "marketing_communication_preferences"
              description:
                type: string
                description: Human-readable description of the purpose
                example: "Preferences for marketing communication channels and frequency"
              version:
                type: string
                description: The specific version of the purpose bound to this consent (e.g., v1, v2)
                example: "v1"
              displayName:
                type: string
                description: Human-readable display name of the purpose version
                example: "Marketing Communication Preferences"
              properties:
                type: object
                description: Key-value properties of the purpose version
                additionalProperties:
                  type: string
                example:
                  category: "marketing"
              elements:
                type: array
                description: List of consent elements in this purpose with enriched details
                items:
                  allOf:
                    - $ref: "#/components/schemas/ConsentElementApprovalItem"
                    - type: object
                      required:
                        - elementId
                        - name
                        - namespace
                        - version
                        - type
                      properties:
                        elementId:
                          type: string
                          description: Unique identifier of the consent element
                          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        version:
                          type: string
                          description: The specific version of the element bound to this consent purpose (e.g., v1, v2)
                          example: "v1"
                        displayName:
                          type: string
                          description: Human-readable display name of the element version
                          example: "User Email Address"
                        mandatory:
                          type: boolean
                          description: Whether this element is mandatory for the consent (from purpose definition)
                          example: true
                        type:
                          type: string
                          enum: [basic, json, xml]
                          description: Element type from the consent element definition
                          example: "basic"
                        description:
                          type: string
                          description: Element description from the consent element definition
                          example: "Allows access to the user's first name"
                        properties:
                          type: object
                          additionalProperties:
                            type: string
                          description: Element properties from the consent element definition
                          example:
                            jsonPath: "$.personal.firstName"
                            resourcePath: "/user/{nic}"
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value attributes associated with the consent
          example:
            channel: "mobile"
            region: "US"
        authorizations:
          type: array
          description: List of authorizations associated with this consent
          items:
            type: object
            properties:
              id:
                type: string
                example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              userId:
                type: string
                nullable: true
                description: User identifier. Omitted from response when null.
                example: "user-456"
              type:
                type: string
                example: "authorization"
              status:
                type: string
                example: "APPROVED"
              resources:
                type: object
                description: Authorization resources (always present, empty object if not set)
                example:
                  accountIds: ["123456", "789012"]
              updatedTime:
                type: integer
                format: int64
                example: 1699651200
      required:
        - id
        - type
        - groupId
        - status
        - createdTime
        - updatedTime
        - purposes
    ConsentIdsResponse:
      type: object
      description: Response payload containing consent IDs matching the attribute search criteria.
      properties:
        consentIds:
          description: Array of consent IDs that match the search criteria, sorted alphabetically.
          type: array
          items:
            type: string
          example: ["123e4567-e89b-12d3-a456-426614174001", "123e4567-e89b-12d3-a456-426614174002", "123e4567-e89b-12d3-a456-426614174003"]
        count:
          description: The number of consent IDs returned.
          type: integer
          example: 3
    ConsentAttributeSearchResponse:
      $ref: "#/components/schemas/ConsentIdsResponse"
    ConsentElementCreateRequest:
      type: object
      required:
        - name
        - type
      description: |
        Request object for creating a consent element. All fields marked as required must be provided.

        **Type Handler Architecture:**
        Each element type has specific property requirements:
        - **basic**: No mandatory properties (any properties are optional)
        - **json**: Requires `schema` field
        - **xml**: Requires `schema` field

        **Batch Creation:**
        When creating multiple elements in a batch:
        - Each element name must be unique within the batch
        - Each element name must not already exist in the organization
        - If any validation fails, the entire batch is rolled back (atomic operation)
      properties:
        name:
          type: string
          maxLength: 255
          description: |
            The name/identifier of the consent element. Must be unique within the organization.
            Database constraint: UNIQUE KEY unique_name_per_org (NAME, ORG_ID)
            Batch constraint: Must be unique within the batch request
          example: "license_read"
        namespace:
          type: string
          maxLength: 255
          description: |
            The namespace of the consent element. Together with `name`, must be unique within the organization.
            Used to logically group related elements (e.g., "personal", "banking", "healthcare").
            If omitted or empty, the `default` namespace is used.
          example: "licensing"
        description:
          type: string
          maxLength: 1024
          description: Optional description providing additional context about the element
          example: "Allows accessing license API"
        displayName:
          type: string
          description: Human-readable display name for the element (used in UIs)
          example: "License Read"
        type:
          type: string
          enum:
            - basic
            - json
            - xml
          description: |
            The type of the element:
            - 'basic': No mandatory properties
            - 'json': Requires `schema` field
            - 'xml': Requires `schema` field
          example: "basic"
        schema:
          type: string
          description: Validation schema (required for json and xml types)
          example: "{\"type\":\"object\"}"
        properties:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value map of extra properties for the element
          example:
            value: "license:read"
    ConsentElementBulkCreateResponse:
      type: object
      description: Response for a bulk consent element creation request. Contains a per-item result for every element in the request, plus summary metadata.
      required:
        - metadata
        - results
      properties:
        metadata:
          type: object
          required:
            - traceId
            - total
            - succeeded
            - failed
          properties:
            traceId:
              type: string
              format: uuid
              description: Trace identifier for this request
              example: "4f9c2d7a-8b1e-4f9c-2d7a-8b1e4f9c2d7a"
            total:
              type: integer
              description: Total number of elements in the request
              example: 3
            succeeded:
              type: integer
              description: Number of elements successfully created
              example: 2
            failed:
              type: integer
              description: Number of elements that failed validation
              example: 1
        results:
          type: array
          description: Per-item results in the same order as the request array
          items:
            type: object
            required:
              - index
              - status
            properties:
              index:
                type: integer
                description: Zero-based index of this element in the original request array
                example: 0
              status:
                type: string
                enum: [SUCCESS, FAILED]
                description: Whether this element was created successfully or failed validation
                example: "SUCCESS"
              data:
                description: Created element data — present when status is SUCCESS
                allOf:
                  - $ref: "#/components/schemas/ConsentElementCreateResponse"
              error:
                type: object
                description: Error details — present when status is FAILED
                required:
                  - code
                  - message
                properties:
                  code:
                    type: string
                    example: "CONFLICT"
                  message:
                    type: string
                    example: "Element already exists"
                  description:
                    type: string
                    example: "Element name 'user_email' already exists in namespace 'personal'"
    ConsentElementCreateResponse:
      type: object
      description: |
        Response returned when a consent element is created. Contains element identity fields
        plus the content of the initial version (version 1) that is automatically created.
      required:
        - elementId
        - name
        - namespace
        - type
        - version
        - createdTime
      properties:
        elementId:
          type: string
          description: Unique identifier for the newly created consent element
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent element
          example: "license_read"
        namespace:
          type: string
          description: The namespace of the consent element
          example: "licensing"
        type:
          type: string
          enum: [basic, json, xml]
          description: The element type
          example: "basic"
        version:
          type: string
          description: The initial version identifier (always v1)
          example: "v1"
        displayName:
          type: string
          description: Human-readable display name for the element
          example: "License Read"
        description:
          type: string
          description: Description of the element
          example: "Allows accessing license API"
        schema:
          type: string
          description: Validation schema (present for json and xml types)
          example: '{"type":"object"}'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value map of extra properties
          example:
            value: "license:read"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this element and its initial version were created.
          example: 1742860800000
    ConsentElementSummaryResponse:
      type: object
      description: |
        Summary response for a consent element. Always includes immutable fields, the latest version number,
        and the latest version's displayName and description.
        Returned by `GET /consent-elements` when `details=false` (default).
      required:
        - elementId
        - name
        - namespace
        - type
        - version
        - createdTime
      properties:
        elementId:
          type: string
          description: Unique identifier for the consent element
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent element
          example: "first_name"
        namespace:
          type: string
          description: The namespace of the consent element
          example: "personal"
        type:
          type: string
          enum: [basic, json, xml]
          description: The element type (immutable)
          example: "basic"
        version:
          type: string
          description: The latest version identifier (e.g. v3). When `version` query param is provided, reflects that version instead.
          example: "v3"
        displayName:
          type: string
          description: Human-readable display name from the latest (or requested) version.
          example: "First Name"
        description:
          type: string
          description: Description from the latest (or requested) version.
          example: "Access to the user's first name"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this element was created.
          example: 1736467200000
    ConsentElementListResponse:
      type: object
      description: |
        The response from a successful consent element list/search query.
        When `details=false` (default), `data` items conform to `ConsentElementSummaryResponse`.
        When `details=true`, `data` items conform to `ConsentElementVersionResponse`.
      properties:
        data:
          type: array
          description: Array of consent elements — summary shape by default, full version content when `details=true`
          items:
            oneOf:
              - $ref: "#/components/schemas/ConsentElementSummaryResponse"
              - $ref: "#/components/schemas/ConsentElementVersionResponse"
        metadata:
          $ref: "#/components/schemas/ConsentSearchMetadata"
      required:
        - data
        - metadata
    PurposeCreateRequest:
      type: object
      required:
        - name
        - elements
      description: |
        Request object for creating a consent purpose.

        **Element Validation:**
        All element references in the `elements` array must reference existing consent elements
        in the organization by name, namespace, and version. The API will validate each element reference
        and fail the request if any element doesn't exist or the version doesn't match.

        **Uniqueness:**
        Purpose names must be unique within the organization.
      properties:
        name:
          type: string
          maxLength: 255
          description: |
            The name/identifier of the purpose. Must be unique within the organization.
            Use descriptive names that indicate the logical grouping (e.g., "marketing_preferences",
            "account_access_permissions").
          example: "marketing_communication_preferences"
        displayName:
          type: string
          maxLength: 255
          description: Human-readable display name for the initial purpose version (used in UIs)
          example: "Marketing Communication Preferences"
        description:
          type: string
          maxLength: 1024
          description: Optional description providing additional context about the purpose
          example: "User preferences related to marketing communications"
        properties:
          type: object
          description: |
            A key-value map of additional, non-standard attributes associated with this purpose version.
            Values must be strings.
          additionalProperties:
            type: string
          example:
            category: "marketing"
            region: "APAC"
        elements:
          type: array
          minItems: 1
          description: |
            Array of element references with mandatory flags. Each reference must specify an existing element by `name` (and optionally `namespace` and `version`). At least one element is required.
          items:
            $ref: "#/components/schemas/PurposeVersionElementItem"
          example:
            - name: "user_email"
              namespace: "personal"
              version: "v1"
              mandatory: true
            - name: "user_mobile"
              namespace: "personal"
              version: "v1"
              mandatory: false
    ConsentPurposeCreateResponse:
      type: object
      description: |
        Response returned when a consent purpose is created. Contains purpose identity fields
        plus the content of the initial version (version 1) that is automatically created.
      required:
        - purposeId
        - name
        - groupId
        - version
        - elements
        - createdTime
      properties:
        purposeId:
          type: string
          description: Unique identifier for the newly created consent purpose
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent purpose
          example: "marketing_communication_preferences_purpose"
        groupId:
          type: string
          description: The group ID associated with this purpose (immutable)
          example: "group-001"
        version:
          type: string
          description: The initial version identifier (always v1)
          example: "v1"
        displayName:
          type: string
          description: Human-readable display name for this version
          example: "Marketing Communication Preferences"
        description:
          type: string
          description: Description of this purpose version
          example: "User preferences related to marketing communications"
        properties:
          type: object
          description: Key-value map of additional attributes associated with this purpose version
          additionalProperties:
            type: string
          example:
            category: "marketing"
        elements:
          type: array
          description: List of element version references with mandatory flags for this version
          items:
            $ref: "#/components/schemas/PurposeVersionElementResponse"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this purpose and its initial version were created.
          example: 1742860800000
    ConsentPurposeSummaryResponse:
      type: object
      description: Summary response for a consent purpose. Always includes immutable identity fields, the latest version number, and the latest version's displayName and description. Returned by default when `details=false`.
      required:
        - purposeId
        - name
        - groupId
        - version
        - createdTime
      properties:
        purposeId:
          type: string
          description: Unique identifier for the consent purpose
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent purpose (immutable)
          example: "marketing_communication_preferences_purpose"
        groupId:
          type: string
          description: The group ID associated with this purpose (immutable)
          example: "group-001"
        version:
          type: string
          description: The latest version of this purpose (or the requested version if purposeVersion was specified)
          example: "v3"
        displayName:
          type: string
          description: Human-readable display name from the latest (or requested) version.
          example: "Marketing Communication Preferences"
        description:
          type: string
          description: Description from the latest (or requested) version.
          example: "User preferences related to marketing communications"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this purpose was created.
          example: 1736467200000
    PurposeListResponse:
      type: object
      required:
        - data
        - metadata
      description: Response object for purpose list/search operations
      properties:
        data:
          type: array
          description: Array of purpose items — summary shape by default, full version content when `details=true`
          items:
            oneOf:
              - $ref: "#/components/schemas/ConsentPurposeSummaryResponse"
              - $ref: "#/components/schemas/ConsentPurposeVersionResponse"
        metadata:
          $ref: "#/components/schemas/ConsentSearchMetadata"
    ConsentElementVersionCreateRequest:
      type: object
      description: |
        Request for creating a new version of a consent element.
        Versions are immutable once created — to change content, create a new version.
        The element's `name`, `namespace`, and `type` are fixed at element creation time and cannot be changed across versions.
      properties:
        displayName:
          type: string
          description: Human-readable display name for this version (used in UIs)
          example: "First Name V2"
        description:
          type: string
          maxLength: 1024
          description: Description for this version
          example: "Updated first name access"
        schema:
          type: string
          description: Validation schema (required when element type is json or xml)
          example: '{"type":"object"}'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value map of extra properties for this version
          example:
            resourcePath: "/Patient/{firstName}"
            jsonPath: "$.patient.firstName"
    ConsentElementVersionResponse:
      type: object
      description: Full detail response for a specific version of a consent element
      required:
        - elementId
        - name
        - namespace
        - version
        - type
        - createdTime
      properties:
        elementId:
          type: string
          description: Unique identifier for the consent element
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent element
          example: "first_name"
        namespace:
          type: string
          description: The namespace of the consent element
          example: "personal"
        version:
          type: string
          description: The version identifier
          example: "v1"
        type:
          type: string
          enum: [basic, json, xml]
          description: The element type
          example: "basic"
        displayName:
          type: string
          description: Human-readable display name
          example: "First Name"
        description:
          type: string
          description: Description of this version
          example: "Allows access to the user's first name"
        schema:
          type: string
          description: Validation schema (present for json and xml types)
          example: '{"type":"object"}'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Key-value properties for this version
          example:
            resourcePath: "/Patient/{firstName}"
            jsonPath: "$.patient.firstName"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this version was created.
          example: 1736467200000
    ConsentElementVersionListResponse:
      type: object
      description: Response for listing all versions of a consent element
      required:
        - elementId
        - name
        - namespace
        - type
        - versions
      properties:
        elementId:
          type: string
          description: Unique identifier for the consent element
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent element
          example: "first_name"
        namespace:
          type: string
          description: The namespace of the consent element
          example: "personal"
        type:
          type: string
          enum: [basic, json, xml]
          description: The element type (immutable — shared across all versions)
          example: "basic"
        versions:
          type: array
          description: List of versions ordered by version number (newest first)
          items:
            $ref: "#/components/schemas/ConsentElementVersionItem"
    ConsentElementVersionItem:
      type: object
      description: |
        Version detail for a consent element as returned in list responses.
        The `elementId`, `name`, `namespace`, and `type` are hoisted to the parent `ConsentElementVersionListResponse`
        and are not repeated in each item.
      required:
        - version
        - createdTime
      properties:
        version:
          type: string
          description: The version identifier
          example: "v2"
        displayName:
          type: string
          description: Human-readable display name for this version
          example: "First Name V2"
        description:
          type: string
          description: Description of this version
          example: "Updated access to the user's first name"
        schema:
          type: string
          description: Validation schema (present for json and xml types)
          example: '{"type":"object"}'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Key-value properties for this version
          example:
            resourcePath: "/Patient/{firstName}"
            jsonPath: "$.patient.firstName"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this version was created.
          example: 1736467200000
    ConsentPurposeVersionCreateRequest:
      type: object
      required:
        - elements
      description: |
        Request for creating a new version of a consent purpose.
        Versions are immutable once created — to change elements, create a new version.

        Each element reference must point to an existing element version.
      properties:
        displayName:
          type: string
          description: Human-readable display name for this version (used in UIs)
          example: "Medical Data Access V2"
        description:
          type: string
          maxLength: 1024
          description: Description for this version
          example: "Updated access to basic medical record fields"
        properties:
          type: object
          description: A key-value map of additional, non-standard attributes for this version
          additionalProperties:
            type: string
          example:
            category: "marketing"
        elements:
          type: array
          minItems: 1
          description: List of element version references with mandatory flags
          items:
            $ref: "#/components/schemas/PurposeVersionElementItem"
    ConsentPurposeVersionResponse:
      type: object
      description: Full detail response for a specific version of a consent purpose
      required:
        - purposeId
        - name
        - groupId
        - version
        - elements
        - createdTime
      properties:
        purposeId:
          type: string
          description: Unique identifier for the consent purpose
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent purpose
          example: "medical_data_access"
        groupId:
          type: string
          description: The group ID associated with this purpose (immutable)
          example: "group-001"
        version:
          type: string
          description: The version identifier
          example: "v1"
        displayName:
          type: string
          description: Human-readable display name
          example: "Medical Data Access V1"
        description:
          type: string
          description: Description of this version
          example: "Access to basic medical record fields"
        properties:
          type: object
          description: Key-value map of additional attributes associated with this purpose version
          additionalProperties:
            type: string
          example:
            category: "medical"
        elements:
          type: array
          description: List of element version references with mandatory flags
          items:
            $ref: "#/components/schemas/PurposeVersionElementResponse"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this version was created.
          example: 1736467200000
    ConsentPurposeVersionListResponse:
      type: object
      description: Response for listing all versions of a consent purpose
      required:
        - purposeId
        - name
        - groupId
        - versions
      properties:
        purposeId:
          type: string
          description: Unique identifier for the consent purpose
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent purpose (immutable across versions)
          example: "marketing_communication_preferences"
        groupId:
          type: string
          description: The group ID associated with this purpose (immutable)
          example: "group-001"
        versions:
          type: array
          description: List of versions ordered by version number (newest first)
          items:
            $ref: "#/components/schemas/ConsentPurposeVersionItem"
    ConsentPurposeVersionItem:
      type: object
      description: |
        Version detail for a consent purpose as returned in list responses.
        The `purposeId` and `name` are hoisted to the parent `ConsentPurposeVersionListResponse`
        and are not repeated in each item.
      required:
        - version
        - elements
        - createdTime
      properties:
        version:
          type: string
          description: The version identifier
          example: "v2"
        displayName:
          type: string
          description: Human-readable display name for this version
          example: "Marketing Communication Preferences V2"
        description:
          type: string
          description: Description of this version
          example: "Updated user preferences for marketing communications"
        properties:
          type: object
          additionalProperties:
            type: string
          description: Key-value map of additional attributes associated with this version
          example:
            category: "marketing"
            region: "global"
        elements:
          type: array
          description: List of element version references with mandatory flags for this version
          items:
            $ref: "#/components/schemas/PurposeVersionElementResponse"
        createdTime:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when this version was created.
          example: 1740787200000
    PurposeVersionElementResponse:
      type: object
      required:
        - elementId
        - name
        - namespace
        - version
        - mandatory
      description: |
        A resolved element reference within a purpose version response.
        The server always returns elementId, name, namespace, and the resolved version.
      properties:
        elementId:
          type: string
          description: The unique identifier of the consent element
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: The name/identifier of the consent element
          example: "user_email"
        namespace:
          type: string
          description: The namespace of the consent element
          example: "personal"
        version:
          type: string
          description: The specific version of the element referenced in this purpose version (e.g., v1, v2)
          example: "v1"
        mandatory:
          type: boolean
          description: |
            Whether this element must be approved for the consent to be valid.
            - `true`: Element approval is required
            - `false`: Element approval is optional
          example: true
    PurposeVersionElementItem:
      type: object
      required:
        - name
        - mandatory
      description: A reference to a consent element within a purpose version, identified by name, namespace, and version. If `namespace` is not specified, the default namespace is used. If `version` is not specified, the latest version of the element is used.
      properties:
        name:
          type: string
          description: The name of the consent element
          example: "user_email"
        namespace:
          type: string
          description: The namespace of the consent element. If omitted, the default namespace is used.
          example: "personal"
        version:
          type: string
          description: The specific version of the element to reference (e.g., v1, v2). If omitted, the latest version is used.
          example: "v1"
        mandatory:
          type: boolean
          description: |
            Whether this element must be approved for the consent to be valid.
            - `true`: Element approval is required
            - `false`: Element approval is optional
          example: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic Authentication using username and password.