openapi: 3.1.0
info:
  title: ONE Platform Public API - Transformations
  version: 1.0.0
  license:
    name: ATACCAMA PROPRIETARY/CONFIDENTIAL
    url: https://www.ataccama.com
servers:
  - url: https://server1.com/api
security:
  - JWT: []
paths:
  /transformations/v1/plans/{planUrn}/executions:
    post:
      tags:
        - Transformation Plans
      summary: Trigger plan execution
      description: |
        Initiates asynchronous execution of a published transformation plan.
      operationId: triggerPlanExecution
      parameters:
        - name: planUrn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PlanUrn'
      responses:
        '202':
          description: Execution initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanExecution'
        '400':
          description: Bad Request - Invalid request parameters
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: bad_request
                title: Bad Request
                detail: Invalid plan URN format
        '401':
          description: Unauthorized - Missing or invalid authentication
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: unauthorized
                title: Unauthorized
                detail: Missing or invalid authentication token
        '403':
          description: Forbidden - Insufficient permissions (requires PLAN:RUN)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: forbidden
                title: Forbidden
                detail: User does not have PLAN:RUN permission
        '404':
          description: Plan Not Found - Specified plan does not exist
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: plan_not_found
                title: Plan Not Found
                detail: Transformation plan with URN 'urn:ata:acme:transformations:plan:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f' was not found
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: internal_error
                title: Internal Server Error
                detail: An unexpected error occurred
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    PlanUrn:
      type: string
      format: uri
      pattern: ^urn:ata:[a-z0-9][a-z0-9\-]{0,62}:transformations:plan:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: |
        A URN identifying a Transformation Plan resource in the Transformations API.

        Format: urn:ata:{tenant}:transformations:plan:{uuid}

        Example: urn:ata:acme:transformations:plan:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f
      example: urn:ata:acme:transformations:plan:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f
    ProcessingWorkflowUrn:
      type: string
      format: uri
      pattern: ^urn:ata:[a-z0-9][a-z0-9\-]{0,62}:processing:workflow:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: |
        A URN identifying a Processing Workflow.

        Format: urn:ata:{tenant}:processing:workflow:{uuid}

        Example: urn:ata:acme-corp:processing:workflow:123e4567-e89b-12d3-a456-426614174000
      example: urn:ata:acme-corp:processing:workflow:123e4567-e89b-12d3-a456-426614174000
    ExecutionStatus:
      type: string
      description: |
        @ExtensibleEnum Status of a plan execution.
      examples:
        - RUNNING
        - COMPLETED
        - FAILED
    PlanExecution:
      type: object
      description: Represents an execution instance of a transformation plan
      required:
        - workflowUrn
        - planUrn
        - status
        - createdAt
      properties:
        workflowUrn:
          $ref: '#/components/schemas/ProcessingWorkflowUrn'
        planUrn:
          $ref: '#/components/schemas/PlanUrn'
        status:
          $ref: '#/components/schemas/ExecutionStatus'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of execution start
          example: '2025-01-15T10:30:00Z'
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          description: Error type identifier
          example: RESOURCE_NOT_FOUND
        title:
          type: string
          description: Short, human-readable summary of the problem type
          example: Resource Not Found
        detail:
          type: string
          description: Detailed specific explanation of the problem
          example: Table 'urn:ata:acme:reference-data:tables:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f' was not found
      required:
        - type
        - title
        - detail
