@celigo/api-specs 0.2.1

package/dist/asynchelper.yml

@@ -0,0 +1,3391 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Async Helpers
+  description: API for managing Celigo async helpers — submit/status/result polling definitions for external asynchronous job APIs.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing async helpers in Celigo. An async helper teaches an
+      export or import step how to talk to an *asynchronous* external API — one
+      that does not return results immediately but instead acknowledges the
+      request and processes it in the background (the "fire-and-check-back"
+      pattern: HTTP 202 responses, job tickets, feed / document IDs, etc.).
+
+      An async helper is NOT an independent runtime resource. It only does
+      anything when referenced from an export or import via `http._asyncHelperId`.
+      It bundles the polling configuration (how long to wait, how often to poll,
+      where the status lives in the response, which values mean in-progress /
+      done / error) plus references to the two export resources that do the
+      actual work:
+
+      - a required **status export** (`http.status._exportId`) that the platform
+        calls on each poll to check whether the background job is finished, and
+      - a **result export** (`http.result._exportId`) that fetches the final
+        payload once the job reports done.
+
+      The status export and the result export must themselves be ordinary
+      (synchronous) exports — they cannot reference an async helper of their own.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Async Helpers
+    description: |-
+      API for managing async helper resources in Celigo. Async helpers define how
+      integrator.io polls an external system's asynchronous job API: submitting a
+      request, checking its status until completion, and retrieving the result.
+
+      An async helper ties together three phases:
+
+      - **Submit** -- initiate the remote job (or reuse the status endpoint).
+      - **Status** -- poll until the job reaches a done or error state.
+      - **Result** -- fetch the final payload once the status indicates success.
+
+      Each phase references an export resource that contains the HTTP
+      configuration (connection, method, relative URI, etc.).
+
+      ## Async helper schema
+
+      {% openapi-schemas spec="asynchelper" schemas="AsyncHelper" grouped="true" %}
+paths:
+  /v1/asynchelpers:
+    get:
+      x-internal: false
+      operationId: listAsyncHelpers
+      tags:
+        - Async Helpers
+      summary: List async helpers
+      description: Returns an array of all async helper resources in the account.
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of records to return per page.
+          schema:
+            type: integer
+            minimum: 1
+        - $ref: '#/components/parameters/After'
+        - name: externalId
+          in: query
+          description: Filter to async helpers matching this exact external identifier.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Array of async helper objects.
+          headers:
+            Link:
+              description: |-
+                RFC-5988 pagination links. When more pages remain, includes a `<...>; rel="next"` entry;
+                absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/AsyncHelper'
+              examples:
+                list:
+                  summary: List with one async helper
+                  value:
+                    - _id: 64a1b2c3d4e5f60011223344
+                      lastModified: '2026-04-15T14:30:15Z'
+                      name: Salesforce Bulk Query Helper
+                      _templateId: 5c6c135fc802b3146e12eecf
+                      _sourceId: 6256b8c0cddb8a1ba55198d5
+                      http:
+                        submit:
+                          sameAsStatus: true
+                        status:
+                          _exportId: 63b1c2d3e4f5a60011334455
+                          statusPath: status
+                          pollWaitTime: 4
+                          initialWaitTime: 1
+                          inProgressValues:
+                            - InProgress
+                            - UploadComplete
+                          doneValues:
+                            - JobComplete
+                          errorValues:
+                            - Failed
+                            - Aborted
+                        result:
+                          _exportId: 63c1d2e3f4a5b60011445566
+        '204':
+          description: No async helpers exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+      x-celigo-ai-guidance:
+        - |-
+          Returns a list of all async helpers configured in the account.
+          If no async helpers exist, a 204 response with no body will be returned.
+    post:
+      x-internal: false
+      operationId: createAsyncHelper
+      tags:
+        - Async Helpers
+      summary: Create an async helper
+      description: |-
+        Creates a new async helper resource. The referenced
+        `http.status._exportId` must be an existing export resource. If
+        `http.submit.sameAsStatus` is `false`, also set
+        `http.submit.resourcePath` to extract the async job identifier.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AsyncHelperRequest'
+            examples:
+              same_as_status:
+                summary: Submit reuses the status endpoint
+                value:
+                  name: Salesforce Bulk Query Helper
+                  http:
+                    submit:
+                      sameAsStatus: true
+                    status:
+                      _exportId: 63b1c2d3e4f5a60011334455
+                      statusPath: status
+                      pollWaitTime: 4
+                      initialWaitTime: 1
+                      inProgressValues:
+                        - InProgress
+                        - UploadComplete
+                      doneValues:
+                        - JobComplete
+                      errorValues:
+                        - Failed
+                        - Aborted
+                    result:
+                      _exportId: 63c1d2e3f4a5b60011445566
+              separate_submit:
+                summary: Separate submit endpoint
+                value:
+                  name: Report Generation Helper
+                  http:
+                    submit:
+                      sameAsStatus: false
+                      resourcePath: jobId
+                    status:
+                      _exportId: 63b1c2d3e4f5a60011334455
+                      statusPath: job.state
+                      pollWaitTime: 5
+                      inProgressValues:
+                        - Pending
+                        - Processing
+                      doneValues:
+                        - Completed
+                      doneWithoutDataValues:
+                        - NoData
+                      errorValues:
+                        - Failed
+                    result: {}
+      responses:
+        '201':
+          description: Async helper created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AsyncHelper'
+              examples:
+                created:
+                  summary: Newly created async helper
+                  value:
+                    _id: 64a1b2c3d4e5f60011223344
+                    lastModified: '2026-04-29T14:30:00Z'
+                    name: Salesforce Bulk Query Helper
+                    http:
+                      submit:
+                        sameAsStatus: true
+                      status:
+                        _exportId: 63b1c2d3e4f5a60011334455
+                        statusPath: status
+                        pollWaitTime: 4
+                        initialWaitTime: 1
+                        inProgressValues:
+                          - InProgress
+                          - UploadComplete
+                        doneValues:
+                          - JobComplete
+                        errorValues:
+                          - Failed
+                          - Aborted
+                      result:
+                        _exportId: 63c1d2e3f4a5b60011445566
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+      x-celigo-ai-guidance:
+        - |-
+          Creates a new async helper. The `http.status._exportId` (status export)
+          and `http.status.statusPath` are required. The status and result exports
+          referenced here must be ordinary exports that do not themselves reference
+          an async helper.
+  /v1/asynchelpers/{_id}:
+    get:
+      x-internal: false
+      operationId: getAsyncHelperById
+      tags:
+        - Async Helpers
+      summary: Get an async helper
+      description: Returns a single async helper resource by its ID.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Async helper ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: asynchelpers
+      responses:
+        '200':
+          description: The async helper record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AsyncHelper'
+              examples:
+                detail:
+                  summary: Async helper with all phases configured
+                  value:
+                    _id: 64a1b2c3d4e5f60011223344
+                    lastModified: '2026-04-15T14:30:15Z'
+                    name: Salesforce Bulk Query Helper
+                    _templateId: 5c6c135fc802b3146e12eecf
+                    _sourceId: 6256b8c0cddb8a1ba55198d5
+                    http:
+                      submit:
+                        sameAsStatus: true
+                      status:
+                        _exportId: 63b1c2d3e4f5a60011334455
+                        statusPath: status
+                        pollWaitTime: 4
+                        initialWaitTime: 1
+                        inProgressValues:
+                          - InProgress
+                          - UploadComplete
+                        doneValues:
+                          - JobComplete
+                        errorValues:
+                          - Failed
+                          - Aborted
+                      result:
+                        _exportId: 63c1d2e3f4a5b60011445566
+        '400':
+          description: The `_id` is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  summary: Invalid ObjectId format
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No async helper exists with the given ID.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Async helper does not exist
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: AsyncHelper not found.
+      x-celigo-ai-guidance:
+        - |-
+          Returns the complete configuration of a specific async helper, including
+          its polling configuration and the status / result export references.
+    put:
+      x-internal: false
+      operationId: updateAsyncHelper
+      tags:
+        - Async Helpers
+      summary: Update an async helper
+      description: |-
+        Updates an existing async helper with the provided data. This is a full
+        replacement — all required fields must be included in the request body.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Async helper ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: asynchelpers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AsyncHelperRequest'
+            examples:
+              update:
+                summary: Update async helper with new error values
+                value:
+                  name: Salesforce Bulk Query Helper
+                  http:
+                    submit:
+                      sameAsStatus: true
+                    status:
+                      _exportId: 63b1c2d3e4f5a60011334455
+                      statusPath: status
+                      pollWaitTime: 4
+                      initialWaitTime: 1
+                      inProgressValues:
+                        - InProgress
+                        - UploadComplete
+                      doneValues:
+                        - JobComplete
+                      errorValues:
+                        - Failed
+                        - Aborted
+                        - TimedOut
+                    result:
+                      _exportId: 63c1d2e3f4a5b60011445566
+      responses:
+        '200':
+          description: Async helper updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AsyncHelper'
+              examples:
+                updated:
+                  summary: Async helper with new error value applied
+                  value:
+                    _id: 64a1b2c3d4e5f60011223344
+                    lastModified: '2026-04-16T09:05:42Z'
+                    name: Salesforce Bulk Query Helper
+                    http:
+                      submit:
+                        sameAsStatus: true
+                      status:
+                        _exportId: 63b1c2d3e4f5a60011334455
+                        statusPath: status
+                        pollWaitTime: 4
+                        initialWaitTime: 1
+                        inProgressValues:
+                          - InProgress
+                          - UploadComplete
+                        doneValues:
+                          - JobComplete
+                        errorValues:
+                          - Failed
+                          - Aborted
+                          - TimedOut
+                      result:
+                        _exportId: 63c1d2e3f4a5b60011445566
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      operationId: deleteAsyncHelper
+      tags:
+        - Async Helpers
+      summary: Delete an async helper
+      description: |-
+        Deletes an async helper. The resource is soft-deleted and retained in
+        the recycle bin for 30 days before permanent removal. If other resources
+        reference this async helper (e.g. exports, flows), the delete is blocked
+        — use `GET /v1/asynchelpers/{_id}/dependencies` to discover dependents
+        first.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Async helper ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: asynchelpers
+      responses:
+        '204':
+          description: Async helper deleted successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-dependency-conflict'
+  /v1/asynchelpers/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listAsyncHelperDependencies
+      tags:
+        - Async Helpers
+      summary: List dependencies of an async helper
+      description: |-
+        Returns the set of resources that depend on the specified resource.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency
+        entries.
+
+        Returns `{}` for both zero-dependency and nonexistent IDs.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: asynchelpers
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: |-
+        Opaque cursor for forward pagination. Pass the value from the `Link`
+        response header (`rel="next"`) to fetch the next page.
+      schema:
+        type: string
+  schemas:
+    items:
+      type: object
+      properties:
+        generate:
+          type: string
+          description: |
+            **Purpose**
+            Defines the target field name in the output object/record.
+
+            **Guidance**
+            This is the PRIMARY FIELD that identifies the output property being created:
+
+            - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
+            - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
+            - For array fields: Set to the array property name, then configure 'buildArrayHelper'
+            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+
+            IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
+            hierarchical structure with nested mappings:
+            ```json
+            {
+              "generate": "customer",
+              "dataType": "object",
+              "status": "Active",
+              "mappings": [
+                {"generate": "firstName", "dataType": "string", "extract": "$.name.first", "status": "Active"}
+              ]
+            }
+            ```
+
+            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
+            within a parent array.
+          examples:
+            - name
+            - address
+            - items
+        dataType:
+          type: string
+          description: |
+            **Purpose**
+            Explicitly declares the data type of the output field, controlling how data is processed and structured.
+
+            **Guidance**
+            This is a REQUIRED field that fundamentally determines mapping behavior:
+
+            **Simple Types (direct value mapping)**
+            - `string`: Text values, converts other types to string representation
+            - `number`: Numeric values, attempts conversion from strings
+            - `boolean`: True/false values, converts truthy/falsy values
+
+            Dates are represented as strings — use `string` for date fields and
+            drive the parsing/formatting through the `extractDateFormat` /
+            `generateDateFormat` / `extractDateTimezone` / `generateDateTimezone`
+            fields. There is no separate `date` enum value.
+
+            **Complex Types (require additional configuration)**
+            - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+
+            **Array Types**
+            - `stringarray`: Array of strings
+            - `numberarray`: Array of numbers
+            - `booleanarray`: Array of booleans
+            - `objectarray`: Array of objects (most common array type)
+            - `arrayarray`: Array of arrays (for matrix/table structures)
+
+            Array dataTypes can be populated two ways: pass a source array through
+            unchanged via `extract` alone (when the source is already an array of
+            the right shape), or construct/iterate via `buildArrayHelper`.
+
+            IMPORTANT: The dataType controls which additional fields are relevant:
+            - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
+            - For object types: 'mappings' array becomes relevant
+            - For array types: `buildArrayHelper` is one option (see above)
+
+            When analyzing existing mappings or generating new ones, always check dataType first
+            to understand what additional fields should be present.
+          x-celigo-ai-guidance:
+            - |-
+              Missing `dataType` is rejected at save with validation error
+              `[mandatory_destination_datatype] Destination datatype is a
+              required field.` When in doubt, use `"string"` — it accepts
+              any source value and the runtime will coerce it.
+          enum:
+            - string
+            - number
+            - boolean
+            - object
+            - stringarray
+            - numberarray
+            - booleanarray
+            - objectarray
+            - arrayarray
+          x-enumDescriptions:
+            string: Text values; converts other types to their string representation.
+            number: Numeric values; attempts conversion from strings.
+            boolean: True/false values; converts truthy/falsy values.
+            object: Nested object that requires child mappings in the `mappings` array.
+            stringarray: Array of string values.
+            numberarray: Array of numeric values.
+            booleanarray: Array of boolean values.
+            objectarray: Array of objects, the most common array type.
+            arrayarray: Array of arrays, used for matrix or table structures.
+          examples:
+            - string
+            - number
+            - object
+            - objectarray
+        extract:
+          type: string
+          description: |
+            **Purpose**
+            Defines how to retrieve data from the input record to populate the output field.
+
+            **Guidance**
+            This field supports THREE DISTINCT PATTERNS that are easily distinguished:
+
+            **1. json Path Syntax**
+            - MUST start with '$.' prefix
+            - Used for precisely targeting data in structured JSON objects
+            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+            - Wildcards like [*] extract multiple values/objects
+
+            ```json
+            "extract": "$.customer.addresses[*]"  // Extracts all addresses
+            ```
+
+            **2. Handlebars Template Syntax**
+            - Contains '{{' and '}}' pattern
+            - Evaluated by the AFE 2.0 handlebars template engine
+            - Can include logic, formatting, and computation
+            - Access input record fields with {{record.fieldName}} notation
+            - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
+            - Valid on `object`, `objectarray`, and primitive-array dataTypes as
+              well as scalars — the rendered template output must parse into the
+              declared shape
+
+            ```json
+            "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
+            ```
+
+            **3. Hard-Coded Value (literal string)**
+            - Does NOT start with '$.'
+            - Does NOT contain handlebars '{{' syntax
+            - System treats it as a literal string value
+            - VERY COMMON for setting static/constant values
+            - Examples: "Active", "USD", "Completed", "true"
+
+            ```json
+            "extract": "primary"  // Sets field value to the literal string "primary"
+            "extract": "true"     // Sets field value to the literal string "true"
+            "extract": "N/A"      // Sets field value to the literal string "N/A"
+            ```
+
+            This third pattern is the simplest and most efficient way to set hard-coded values in your mappings.
+            AI agents should use this pattern whenever a field needs a static value that doesn't come from
+            the input record or require computation.
+
+            **Important implementation details**
+
+            - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
+            - The system maintains this context even in deeply nested mappings
+            - For object mappings without child mappings, extract should return a complete object
+            - When both extract and mappings are defined for objects, extract is applied first
+
+            For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
+            For hard-coded values, simply use the literal string as the extract value.
+          x-celigo-ai-guidance:
+            - |-
+              ## SIZE LIMIT
+              The platform's import save validator caps this field at **1024
+              characters**.  Saves with a longer `extract` are rejected
+              with `[size_limit_exceeded] The maximum size of the field:
+              mappings.<index>.extract in the Import document should be
+              1024 characters`.  This typically only matters for
+              Handlebars templates that build complex strings inline -- if
+              a template is approaching the cap, prefer one of:
+
+              - **Decompose into nested mappings** (set `dataType:
+                "object"` and use child `mappings` -- each child gets
+                its own 1024-char budget).
+              - **Move the logic to a `preMap` hook** so the heavy
+                transformation runs in script and the mapping just reads
+                `record.<computed>`.
+              - **Use a lookup** (`lookupName` + a small `lookups` entry)
+                for value translation that would otherwise need a long
+                `{{#if ...}}{{else if ...}}` chain.
+          examples:
+            - $.fullName
+            - '{{record.fullName}}'
+            - primary
+            - $.lineItems[*].unitPrice
+        extractDateFormat:
+          type: string
+          description: |
+            Specifies the format pattern of the input date string to ensure proper parsing.
+
+            Used on string-typed mappings whose `extract` yields a date. Uses
+            Moment.js-compatible formatting tokens to describe how the incoming date
+            string is structured.
+          examples:
+            - YYYY-MM-DD
+            - MM/DD/YYYY
+            - DD-MMM-YYYY HH:mm:ss
+        extractDateTimezone:
+          type: string
+          description: |
+            Specifies the timezone of the input date string using Olson/IANA timezone identifiers.
+
+            Used on string-typed mappings whose `extract` yields a date; tells the system
+            how to interpret timestamp values from the input system.
+          examples:
+            - UTC
+            - America/New_York
+            - Europe/London
+        generateDateFormat:
+          type: string
+          description: |
+            Specifies the output format pattern when generating a date string or converting
+            from a Date type to String type.
+
+            Uses Moment.js-compatible formatting tokens to define the structure of the resulting
+            date string.
+          examples:
+            - YYYY-MM-DD
+            - MM/DD/YYYY
+            - DD-MMM-YYYY HH:mm:ss
+        generateDateTimezone:
+          type: string
+          description: |
+            Specifies the timezone to apply when generating or converting timestamp values
+            using Olson/IANA timezone identifiers.
+
+            Controls timezone conversion when producing date output.
+          examples:
+            - UTC
+            - America/New_York
+            - Europe/London
+        default:
+          type:
+            - string
+            - 'null'
+          description: |
+            Specifies a fallback value to use when extract returns empty/null or when conditional
+            logic fails and no other mapping supplies a value.
+
+            Explicit JSON `null` is itself a valid fallback: the destination field is written as
+            JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
+            action). Omitting the key entirely means no fallback — the field is left out of the
+            output when the extract is empty (the UI's "Do nothing" action).
+          x-celigo-ai-guidance:
+            - |-
+              `"default": null` and `"default": ""` are distinct saved values, not
+              absent keys: null renders the destination field as JSON null and the
+              empty string renders it as `""` when the extract yields nothing.
+              Preserve them verbatim when editing or migrating a mapping — dropping
+              the key changes runtime behavior from "use null/empty string as
+              default value" to "do nothing" (field omitted from the output).
+          examples:
+            - N/A
+            - '0'
+            - 'false'
+        lookupName:
+          type: string
+          description: |
+            **Purpose**
+            References a lookup table for transforming values during the mapping process.
+
+            **Usage**
+
+            The lookupName refers to a named lookup defined in the lookups array of the same resource.
+
+            ```json
+            {
+              "generate": "countryName",
+              "dataType": "string",
+              "extract": "$.countryCode",
+              "lookupName": "countryCodeToName"
+            }
+            ```
+
+            During processing, the system:
+            1. Extracts the value from the input record (e.g., "US")
+            2. Finds the lookup table with the specified name
+            3. Uses the extracted value as a key in the lookup
+            4. Returns the corresponding value (e.g., "United States")
+
+            **Benefits**
+
+            - **Standardization**: Ensures consistent value translation across mappings
+            - **Centralization**: Define translations once and reference them in multiple places
+            - **Maintainability**: Update all mappings by changing the lookup definition
+            - **Readability**: Makes mappings more descriptive and self-documenting
+
+            The specific lookup capabilities depend on the context where mappings are used.
+          examples:
+            - countryCodeToName
+            - statusMapping
+            - departmentCodes
+        description:
+          type: string
+          description: |
+            Optional free-text annotation that appears in the Mapper sidebar to provide context about
+            the mapping's purpose for collaboration and documentation.
+
+            Has no functional impact on the mapping behavior.
+          examples:
+            - Maps customer name
+            - Converts price to target currency
+            - Formats date for target system
+        sourceDataType:
+          type: string
+          description: |
+            Declares the JSON type of the value produced by `extract`, before any
+            conversion to `dataType`. Same enum as `dataType`. Set on leaf mappings
+            only — parent mappings (with child `mappings` or `buildArrayHelper`)
+            have no extracted value of their own; the children carry their own
+            `sourceDataType`.
+
+            For date fields use `string` (JSON represents dates as strings); the
+            parsing/formatting lives in `extractDateFormat` / `generateDateFormat` /
+            `extractDateTimezone` / `generateDateTimezone`.
+          enum:
+            - string
+            - number
+            - boolean
+            - object
+            - stringarray
+            - numberarray
+            - booleanarray
+            - objectarray
+            - arrayarray
+          x-enumDescriptions:
+            string: Source value is a text string.
+            number: Source value is numeric.
+            boolean: Source value is true or false.
+            object: Source value is a JSON object.
+            stringarray: Source value is an array of strings.
+            numberarray: Source value is an array of numbers.
+            booleanarray: Source value is an array of booleans.
+            objectarray: Source value is an array of objects.
+            arrayarray: Source value is an array of arrays.
+          examples:
+            - string
+            - number
+            - boolean
+            - object
+        mappings:
+          type: array
+          description: |
+            **Purpose**
+            Enables recursive definition of nested object structures through child mapping objects.
+
+            **Guidance**
+            This is the KEY FIELD that implements the recursive pattern at the core of this schema:
+
+            **When to Use**
+            - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
+            - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
+            - NEVER used with simple types (string, number, boolean, date)
+
+            **Behavior**
+            - Each mapping in this array becomes a property of the parent object
+            - The full Mappings schema is repeated recursively at each level
+            - Can be nested to any depth for complex hierarchical structures
+
+            **Context Handling**
+            - Each level of nesting changes the mapping CONTEXT for 'generate'
+            - The extraction CONTEXT always remains the original input record
+            - This means child mappings can pull data from anywhere in the input record
+
+            **Common Patterns**
+
+            **Nested Objects**
+            ```json
+            {
+              "generate": "customer",
+              "dataType": "object",
+              "mappings": [
+                {
+                  "generate": "contact",
+                  "dataType": "object",
+                  "mappings": [
+                    {"generate": "email", "dataType": "string", "extract": "$.customerEmail"}
+                  ]
+                }
+              ]
+            }
+            ```
+
+            **Multiple Fields in Object**
+            ```json
+            {
+              "generate": "address",
+              "dataType": "object",
+              "mappings": [
+                {"generate": "street", "dataType": "string", "extract": "$.address.line1"},
+                {"generate": "city", "dataType": "string", "extract": "$.address.city"},
+                {"generate": "country", "dataType": "string", "extract": "$.address.country"}
+              ]
+            }
+            ```
+
+            IMPORTANT: When analyzing or generating mappings, ALWAYS check if parent.dataType = "object"
+            or if you're inside buildArrayHelper.mappings for objectarray elements. These are the only
+            valid contexts for the mappings array.
+          items:
+            $ref: '#/components/schemas/items'
+          examples:
+            - - generate: firstName
+                extract: $.name.first
+                dataType: string
+                status: Active
+              - generate: lastName
+                extract: $.name.last
+                dataType: string
+                status: Active
+        buildArrayHelper:
+          type: array
+          x-celigo-ai-guidance:
+            - |-
+              Entry-level `extract` accepts an iterating array path
+              (`$.items[*]`), `"$"` (the record root), or omission — a
+              constructed entry (child `mappings` with the extract omitted or
+              `"$"`; the two spellings are equivalent) contributes exactly one
+              element, and entries append in order. Indexed or comma-joined
+              entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
+              processor renders the entire destination array as null with no
+              validation error. To emit a fixed number of static elements, add
+              that many sibling constructed entries — never index the extract.
+          description: |
+            **Purpose**
+            Configures how to construct arrays in the output record, handling various array types and inputs.
+
+            **Guidance**
+            This is the REQUIRED mechanism for ALL array data types:
+
+            **When to Use**
+            - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
+            - Each entry in this array contributes elements to the output array
+            - Multiple entries allow combining data from different input arrays
+
+            **Array Type Handling**
+
+            **For Simple Arrays (stringarray, numberarray, booleanarray)**
+            - Only the 'extract' field is used to pull values
+            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+            - Each result is converted to the appropriate primitive type
+            ```json
+            {
+              "generate": "productNames",
+              "dataType": "stringarray",
+              "buildArrayHelper": [
+                {"extract": "$.products[*].name"}
+              ]
+            }
+            ```
+
+            **For Object Arrays (objectarray) - three patterns**
+
+            1. Extract Only (existing objects):
+            ```json
+            {
+              "generate": "contacts",
+              "dataType": "objectarray",
+              "buildArrayHelper": [
+                {"extract": "$.account.primaryContacts[*]"},  // Pull primary contact objects
+                {"extract": "$.account.secondaryContacts[*]"},  // Pull secondary contact objects
+                {"extract": "$.vendor.contactPersons[*]"},  // Pull vendor contact objects
+                {"extract": "$.subsidiaries[*].mainContact"}  // Pull main contact from each subsidiary
+              ]
+            }
+            ```
+
+            2. Mappings Only (constructed object):
+            ```json
+            {
+              "generate": "contactInfo",
+              "dataType": "objectarray",
+              "buildArrayHelper": [
+                {
+                  "mappings": [  // Creates one object in the array
+                    {"generate": "type", "dataType": "string", "extract": "primary"},
+                    {"generate": "email", "dataType": "string", "extract": "$.primaryEmail"}
+                  ]
+                },
+                {
+                  "mappings": [  // Creates another object in the array
+                    {"generate": "type", "dataType": "string", "extract": "secondary"},
+                    {"generate": "email", "dataType": "string", "extract": "$.secondaryEmail"}
+                  ]
+                }
+              ]
+            }
+            ```
+            Each constructed entry contributes exactly one element, in entry
+            order; writing the entry with `"extract": "$"` is equivalent to
+            omitting the extract (both anchor the element at the record root).
+            A fixed number of static elements is built from that many sibling
+            constructed entries.
+
+            3. Extract AND Mappings (transform input arrays):
+            ```json
+            {
+              "generate": "lineItems",
+              "dataType": "objectarray",
+              "buildArrayHelper": [
+                {
+                  "extract": "$.order.items[*]",  // For each item in the array
+                  "mappings": [  // Transform to this structure using the composite object
+                    {"generate": "sku", "dataType": "string", "extract": "$.order.items.productId"},  // Notice: items is singular
+                    {"generate": "quantity", "dataType": "number", "extract": "$.order.items.qty"},   // Notice: items is singular
+                    {"generate": "orderNumber", "dataType": "string", "extract": "$.order.id"},       // Access parent data
+                    {"generate": "customerName", "dataType": "string", "extract": "$.customerName"}   // Access root data
+                  ]
+                }
+              ]
+            }
+            ```
+
+            **For Arrays of Arrays (arrayarray)**
+            - Similar to objectarray, but inner arrays have empty 'generate' fields
+            - Used for matrix/table structures
+            ```json
+            {
+              "generate": "matrix",
+              "dataType": "arrayarray",
+              "buildArrayHelper": [
+                {
+                  "extract": "$.rows[*]",  // For each row in the rows array
+                  "mappings": [
+                    {
+                      "dataType": "numberarray",  // Note: No generate field for inner arrays
+                      "buildArrayHelper": [
+                        {"extract": "$.rows.columns[*]"}  // Notice: "rows" is singular in the composite object
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+            ```
+
+            **Important details**
+
+            - When both extract and mappings are provided, the system creates special composite objects
+              that maintain hierarchical context during processing
+            - This enables accessing both the current array element AND its parent context
+            - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
+              (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
+              instead omits extract or sets it to exactly "$" — never rewrite "$" into a
+              '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
+              the entire destination array as null without raising a validation error
+            - Each array helper entry acts independently, potentially adding multiple elements
+
+            The buildArrayHelper is the most complex part of the mappings system - always analyze the
+            dataType first to understand which pattern is appropriate.
+          items:
+            type: object
+            properties:
+              extract:
+                type: string
+                description: |
+                  JSON path expression that identifies the input array or values to extract.
+
+                  For objectarray with mappings, this defines which input objects to iterate through.
+                  The JSON path must return either a single object or an array of objects.
+
+                  For a CONSTRUCTED entry (child mappings building exactly one element from
+                  record-root fields and constants), omit this field or set it to exactly "$" —
+                  the two spellings are equivalent. Indexed or comma-joined forms ('$[0]',
+                  '$[0],$[0]') are not valid at the entry level: the processor renders the
+                  entire destination array as null without raising a validation error.
+
+                  The system creates special composite objects during processing to maintain
+                  hierarchical relationships, allowing easy access to both the current array item
+                  and its parent contexts.
+                examples:
+                  - $.items[*]
+                  - $.order.lineItems[*]
+                  - $.parents[*].children[*]
+                  - $
+              sourceDataType:
+                type: string
+                description: |
+                  Declares the JSON type of the input array being iterated, to ensure
+                  proper type handling during array construction. Same enum as `dataType`.
+                enum:
+                  - string
+                  - number
+                  - boolean
+                  - object
+                  - stringarray
+                  - numberarray
+                  - booleanarray
+                  - objectarray
+                  - arrayarray
+                x-enumDescriptions:
+                  string: Input array contains string elements.
+                  number: Input array contains numeric elements.
+                  boolean: Input array contains boolean elements.
+                  object: Input array contains object elements.
+                  stringarray: Input array contains arrays of strings.
+                  numberarray: Input array contains arrays of numbers.
+                  booleanarray: Input array contains arrays of booleans.
+                  objectarray: Input array contains arrays of objects.
+                  arrayarray: Input array contains arrays of arrays.
+                examples:
+                  - string
+                  - number
+                  - boolean
+                  - object
+              default:
+                type:
+                  - string
+                  - 'null'
+                description: |
+                  Specifies a fallback value when the extracted array element is empty or
+                  not found in the input data.
+
+                  Explicit JSON `null` is itself a valid fallback (the element is written as
+                  JSON null); omitting the key means no fallback is applied.
+                examples:
+                  - N/A
+                  - '0'
+                  - 'false'
+              conditional:
+                type: object
+                description: |
+                  Defines conditional rules for including each array element in the result.
+                properties:
+                  when:
+                    type: string
+                    description: |
+                      Specifies the condition that must be met for an array element to be included.
+
+                      'extract_not_empty' only includes elements where the extract field returns a value.
+                    enum:
+                      - extract_not_empty
+                    x-enumDescriptions:
+                      extract_not_empty: Include the array element only when the extract field returns a non-empty value.
+                    examples:
+                      - extract_not_empty
+              mappings:
+                type: array
+                description: |
+                  Contains recursive mapping definitions for complex array element transformations.
+
+                  **Composite object mechanism**
+
+                  When both 'extract' and 'mappings' are used together, the system implements a sophisticated
+                  "composite object" approach that is crucial for AI agents to understand:
+
+                  1. The system starts with the complete input record
+
+                  2. For each array element matched by the extract path, it creates a modified version of
+                     the input record where:
+                     - Array paths in the extract JSON path are REPLACED with single objects
+                     - Each array ([]) in the path is converted to a single object ({})
+                     - This preserves the hierarchical relationship between nested arrays
+
+                  **Example**
+
+                  Given an input record:
+                  ```json
+                  {
+                    "customer": {
+                      "name": "John Doe",
+                      "orders": [
+                        {
+                          "id": "O-001",
+                          "items": [
+                            {"sku": "ABC", "qty": 2},
+                            {"sku": "XYZ", "qty": 1}
+                          ]
+                        },
+                        {
+                          "id": "O-002",
+                          "items": [
+                            {"sku": "DEF", "qty": 3}
+                          ]
+                        }
+                      ]
+                    }
+                  }
+                  ```
+
+                  With extract path: `$.customer.orders[*].items[*]`
+
+                  For each item, the system creates a composite object like:
+                  ```json
+                  {
+                    "customer": {
+                      "name": "John Doe",
+                      "orders": {  // Note: Array replaced with single object
+                        "id": "O-001",
+                        "items": {  // Note: Array replaced with single object
+                          "sku": "ABC",
+                          "qty": 2
+                        }
+                      }
+                    }
+                  }
+                  ```
+
+                  Then in your mappings, you can access:
+                  - The current item: `$.customer.orders.items.sku`
+                  - The parent order: `$.customer.orders.id`
+                  - Top-level data: `$.customer.name`
+
+                  This approach allows for precise mapping from deeply nested structures while maintaining
+                  access to all contextual parent data, without requiring complex array index management.
+
+                  **Implementation guidance**
+
+                  When implementing the composite object mechanism:
+
+                  1. Analyze the extract path to identify all array patterns (`[*]` or `[number]`)
+                  2. For each array in the path, understand that it will be replaced with a single object
+                  3. In the mappings, use paths that reference these arrays as if they were objects
+                  4. Remember that every mapping still has access to the full input record context
+                  5. This mechanism is especially powerful when mapping hierarchical data like:
+                     - Order → Line Items → Taxes/Discounts
+                     - Customer → Addresses → Address Lines
+                     - Invoice → Line Items → Serial Numbers
+
+                  The extract path effectively tells the system "iterate through these arrays",
+                  while the composite object mechanism ensures you can still access both the
+                  current array item AND its parent context during mapping.
+                items:
+                  $ref: '#/components/schemas/items'
+                examples:
+                  - - generate: itemName
+                      extract: $.name
+                      dataType: string
+                      status: Active
+                    - generate: itemPrice
+                      extract: $.price
+                      dataType: number
+                      status: Active
+        status:
+          type: string
+          description: |
+            **Purpose**
+            Required on every mapping entry. Controls whether the mapping is applied.
+
+            **Guidance**
+            Emit `"Active"` for mappings that should run; `"Draft"` saves an
+            in-progress mapping without the Active-only field validations. The
+            API rejects a mapping missing this field
+            (validation error: "Mapping object must have status field present.").
+          x-celigo-ai-guidance:
+            - |-
+              Emit `"Active"` for mappings that should run; `"Draft"` is also
+              accepted and saves the mapping while bypassing the Active-only
+              field validations. The value is case-sensitive. The API rejects:
+              - Missing field: `[status_field_absent] Mapping object must have status field present.`
+              - Wrong case (e.g. `"active"`): `[invalid_status_enums] active is not a valid enum for status field.`
+          enum:
+            - Active
+            - Draft
+          x-enumDescriptions:
+            Active: The mapping is enabled and applied during processing.
+            Draft: In-progress mapping; saved without the Active-only field validations.
+          examples:
+            - Active
+        conditional:
+          type: object
+          description: |
+            **Purpose**
+            Defines conditional processing rules for the entire mapping.
+
+            **Guidance**
+            These conditions determine whether the mapping is applied based on record
+            state or field content:
+
+            **When to Use**
+            - When a mapping should only be applied in specific circumstances
+            - To implement conditional logic without using complex handlebars expressions
+            - For creating mappings that only run during create or update operations
+
+            **Available Conditions**
+
+            - `record_created`: Apply only when creating a new record
+              Useful for setting initial values that should not be overwritten during updates
+
+            - `record_updated`: Apply only when updating an existing record
+              Useful for transformation logic that should only run during updates
+
+            - `extract_not_empty`: Apply only when the extract field returns a value
+              Useful for conditional mapping based on input data availability
+
+            **Example**
+            ```json
+            {
+              "generate": "statusMessage",
+              "dataType": "string",
+              "status": "Active",
+              "extract": "$.status.message",
+              "conditional": {
+                "when": "extract_not_empty"  // Only map when status.message exists
+              }
+            }
+            ```
+          properties:
+            when:
+              type: string
+              description: |
+                Specifies the condition that triggers application of this mapping:
+                - record_created: Apply only when creating a new record
+                - record_updated: Apply only when updating an existing record
+                - extract_not_empty: Apply only when the extract field returns a value
+              enum:
+                - record_created
+                - record_updated
+                - extract_not_empty
+              x-enumDescriptions:
+                record_created: Apply this mapping only when creating a new record.
+                record_updated: Apply this mapping only when updating an existing record.
+                extract_not_empty: Apply this mapping only when the extract field returns a non-empty value.
+              examples:
+                - record_created
+                - record_updated
+                - extract_not_empty
+      required:
+        - dataType
+    Mappings:
+      type: array
+      description: |
+        Array of field mapping configurations for transforming data from one format into another.
+
+        **Guidance**
+
+        This schema is designed around RECURSION as its core architectural principle. Understanding this recursive
+        nature is essential for building effective mappings:
+
+        1. The schema is self-referential by design - a mapping can contain nested mappings of the same structure
+        2. Complex data structures (nested objects, arrays of objects, arrays of arrays of objects) are ALL
+           handled through this recursive pattern
+        3. Each mapping handles one level of the data structure; deeper levels are handled by nested mappings
+
+        When generating mappings programmatically:
+        - For simple fields (string, number, boolean): Create single mapping objects
+        - For objects: Create a parent mapping with nested 'mappings' array containing child field mappings
+        - For arrays: Use 'buildArrayHelper' with extract paths defining array inputs and
+          recursive 'mappings' to define object structures
+
+        The system will process these nested structures recursively during runtime, ensuring proper construction
+        of complex hierarchical data while maintaining excellent performance.
+      items:
+        type: object
+        properties:
+          generate:
+            type: string
+            description: |
+              **Purpose**
+              Defines the target field name in the output object/record.
+
+              **Guidance**
+              This is the PRIMARY FIELD that identifies the output property being created:
+
+              - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
+              - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
+              - For array fields: Set to the array property name, then configure 'buildArrayHelper'
+              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+
+              IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
+              hierarchical structure with nested mappings:
+              ```json
+              {
+                "generate": "customer",
+                "dataType": "object",
+                "status": "Active",
+                "mappings": [
+                  {"generate": "firstName", "dataType": "string", "extract": "$.name.first", "status": "Active"}
+                ]
+              }
+              ```
+
+              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
+              within a parent array.
+            examples:
+              - name
+              - address
+              - items
+          dataType:
+            type: string
+            description: |
+              **Purpose**
+              Explicitly declares the data type of the output field, controlling how data is processed and structured.
+
+              **Guidance**
+              This is a REQUIRED field that fundamentally determines mapping behavior:
+
+              **Simple Types (direct value mapping)**
+              - `string`: Text values, converts other types to string representation
+              - `number`: Numeric values, attempts conversion from strings
+              - `boolean`: True/false values, converts truthy/falsy values
+
+              Dates are represented as strings — use `string` for date fields and
+              drive the parsing/formatting through the `extractDateFormat` /
+              `generateDateFormat` / `extractDateTimezone` / `generateDateTimezone`
+              fields. There is no separate `date` enum value.
+
+              **Complex Types (require additional configuration)**
+              - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+
+              **Array Types**
+              - `stringarray`: Array of strings
+              - `numberarray`: Array of numbers
+              - `booleanarray`: Array of booleans
+              - `objectarray`: Array of objects (most common array type)
+              - `arrayarray`: Array of arrays (for matrix/table structures)
+
+              Array dataTypes can be populated two ways: pass a source array through
+              unchanged via `extract` alone (when the source is already an array of
+              the right shape), or construct/iterate via `buildArrayHelper`.
+
+              IMPORTANT: The dataType controls which additional fields are relevant:
+              - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
+              - For object types: 'mappings' array becomes relevant
+              - For array types: `buildArrayHelper` is one option (see above)
+
+              When analyzing existing mappings or generating new ones, always check dataType first
+              to understand what additional fields should be present.
+            x-celigo-ai-guidance:
+              - |-
+                Missing `dataType` is rejected at save with validation error
+                `[mandatory_destination_datatype] Destination datatype is a
+                required field.` When in doubt, use `"string"` — it accepts
+                any source value and the runtime will coerce it.
+            enum:
+              - string
+              - number
+              - boolean
+              - object
+              - stringarray
+              - numberarray
+              - booleanarray
+              - objectarray
+              - arrayarray
+            x-enumDescriptions:
+              string: Text values; converts other types to their string representation.
+              number: Numeric values; attempts conversion from strings.
+              boolean: True/false values; converts truthy/falsy values.
+              object: Nested object that requires child mappings in the `mappings` array.
+              stringarray: Array of string values.
+              numberarray: Array of numeric values.
+              booleanarray: Array of boolean values.
+              objectarray: Array of objects, the most common array type.
+              arrayarray: Array of arrays, used for matrix or table structures.
+            examples:
+              - string
+              - number
+              - object
+              - objectarray
+          extract:
+            type: string
+            description: |
+              **Purpose**
+              Defines how to retrieve data from the input record to populate the output field.
+
+              **Guidance**
+              This field supports THREE DISTINCT PATTERNS that are easily distinguished:
+
+              **1. json Path Syntax**
+              - MUST start with '$.' prefix
+              - Used for precisely targeting data in structured JSON objects
+              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+              - Wildcards like [*] extract multiple values/objects
+
+              ```json
+              "extract": "$.customer.addresses[*]"  // Extracts all addresses
+              ```
+
+              **2. Handlebars Template Syntax**
+              - Contains '{{' and '}}' pattern
+              - Evaluated by the AFE 2.0 handlebars template engine
+              - Can include logic, formatting, and computation
+              - Access input record fields with {{record.fieldName}} notation
+              - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
+              - Valid on `object`, `objectarray`, and primitive-array dataTypes as
+                well as scalars — the rendered template output must parse into the
+                declared shape
+
+              ```json
+              "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
+              ```
+
+              **3. Hard-Coded Value (literal string)**
+              - Does NOT start with '$.'
+              - Does NOT contain handlebars '{{' syntax
+              - System treats it as a literal string value
+              - VERY COMMON for setting static/constant values
+              - Examples: "Active", "USD", "Completed", "true"
+
+              ```json
+              "extract": "primary"  // Sets field value to the literal string "primary"
+              "extract": "true"     // Sets field value to the literal string "true"
+              "extract": "N/A"      // Sets field value to the literal string "N/A"
+              ```
+
+              This third pattern is the simplest and most efficient way to set hard-coded values in your mappings.
+              AI agents should use this pattern whenever a field needs a static value that doesn't come from
+              the input record or require computation.
+
+              **Important implementation details**
+
+              - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
+              - The system maintains this context even in deeply nested mappings
+              - For object mappings without child mappings, extract should return a complete object
+              - When both extract and mappings are defined for objects, extract is applied first
+
+              For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
+              For hard-coded values, simply use the literal string as the extract value.
+            x-celigo-ai-guidance:
+              - |-
+                ## SIZE LIMIT
+                The platform's import save validator caps this field at **1024
+                characters**.  Saves with a longer `extract` are rejected
+                with `[size_limit_exceeded] The maximum size of the field:
+                mappings.<index>.extract in the Import document should be
+                1024 characters`.  This typically only matters for
+                Handlebars templates that build complex strings inline -- if
+                a template is approaching the cap, prefer one of:
+
+                - **Decompose into nested mappings** (set `dataType:
+                  "object"` and use child `mappings` -- each child gets
+                  its own 1024-char budget).
+                - **Move the logic to a `preMap` hook** so the heavy
+                  transformation runs in script and the mapping just reads
+                  `record.<computed>`.
+                - **Use a lookup** (`lookupName` + a small `lookups` entry)
+                  for value translation that would otherwise need a long
+                  `{{#if ...}}{{else if ...}}` chain.
+            examples:
+              - $.fullName
+              - '{{record.fullName}}'
+              - primary
+              - $.lineItems[*].unitPrice
+          extractDateFormat:
+            type: string
+            description: |
+              Specifies the format pattern of the input date string to ensure proper parsing.
+
+              Used on string-typed mappings whose `extract` yields a date. Uses
+              Moment.js-compatible formatting tokens to describe how the incoming date
+              string is structured.
+            examples:
+              - YYYY-MM-DD
+              - MM/DD/YYYY
+              - DD-MMM-YYYY HH:mm:ss
+          extractDateTimezone:
+            type: string
+            description: |
+              Specifies the timezone of the input date string using Olson/IANA timezone identifiers.
+
+              Used on string-typed mappings whose `extract` yields a date; tells the system
+              how to interpret timestamp values from the input system.
+            examples:
+              - UTC
+              - America/New_York
+              - Europe/London
+          generateDateFormat:
+            type: string
+            description: |
+              Specifies the output format pattern when generating a date string or converting
+              from a Date type to String type.
+
+              Uses Moment.js-compatible formatting tokens to define the structure of the resulting
+              date string.
+            examples:
+              - YYYY-MM-DD
+              - MM/DD/YYYY
+              - DD-MMM-YYYY HH:mm:ss
+          generateDateTimezone:
+            type: string
+            description: |
+              Specifies the timezone to apply when generating or converting timestamp values
+              using Olson/IANA timezone identifiers.
+
+              Controls timezone conversion when producing date output.
+            examples:
+              - UTC
+              - America/New_York
+              - Europe/London
+          default:
+            type:
+              - string
+              - 'null'
+            description: |
+              Specifies a fallback value to use when extract returns empty/null or when conditional
+              logic fails and no other mapping supplies a value.
+
+              Explicit JSON `null` is itself a valid fallback: the destination field is written as
+              JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
+              action). Omitting the key entirely means no fallback — the field is left out of the
+              output when the extract is empty (the UI's "Do nothing" action).
+            x-celigo-ai-guidance:
+              - |-
+                `"default": null` and `"default": ""` are distinct saved values, not
+                absent keys: null renders the destination field as JSON null and the
+                empty string renders it as `""` when the extract yields nothing.
+                Preserve them verbatim when editing or migrating a mapping — dropping
+                the key changes runtime behavior from "use null/empty string as
+                default value" to "do nothing" (field omitted from the output).
+            examples:
+              - N/A
+              - '0'
+              - 'false'
+          lookupName:
+            type: string
+            description: |
+              **Purpose**
+              References a lookup table for transforming values during the mapping process.
+
+              **Usage**
+
+              The lookupName refers to a named lookup defined in the lookups array of the same resource.
+
+              ```json
+              {
+                "generate": "countryName",
+                "dataType": "string",
+                "extract": "$.countryCode",
+                "lookupName": "countryCodeToName"
+              }
+              ```
+
+              During processing, the system:
+              1. Extracts the value from the input record (e.g., "US")
+              2. Finds the lookup table with the specified name
+              3. Uses the extracted value as a key in the lookup
+              4. Returns the corresponding value (e.g., "United States")
+
+              **Benefits**
+
+              - **Standardization**: Ensures consistent value translation across mappings
+              - **Centralization**: Define translations once and reference them in multiple places
+              - **Maintainability**: Update all mappings by changing the lookup definition
+              - **Readability**: Makes mappings more descriptive and self-documenting
+
+              The specific lookup capabilities depend on the context where mappings are used.
+            examples:
+              - countryCodeToName
+              - statusMapping
+              - departmentCodes
+          description:
+            type: string
+            description: |
+              Optional free-text annotation that appears in the Mapper sidebar to provide context about
+              the mapping's purpose for collaboration and documentation.
+
+              Has no functional impact on the mapping behavior.
+            examples:
+              - Maps customer name
+              - Converts price to target currency
+              - Formats date for target system
+          sourceDataType:
+            type: string
+            description: |
+              Declares the JSON type of the value produced by `extract`, before any
+              conversion to `dataType`. Same enum as `dataType`. Set on leaf mappings
+              only — parent mappings (with child `mappings` or `buildArrayHelper`)
+              have no extracted value of their own; the children carry their own
+              `sourceDataType`.
+
+              For date fields use `string` (JSON represents dates as strings); the
+              parsing/formatting lives in `extractDateFormat` / `generateDateFormat` /
+              `extractDateTimezone` / `generateDateTimezone`.
+            enum:
+              - string
+              - number
+              - boolean
+              - object
+              - stringarray
+              - numberarray
+              - booleanarray
+              - objectarray
+              - arrayarray
+            x-enumDescriptions:
+              string: Source value is a text string.
+              number: Source value is numeric.
+              boolean: Source value is true or false.
+              object: Source value is a JSON object.
+              stringarray: Source value is an array of strings.
+              numberarray: Source value is an array of numbers.
+              booleanarray: Source value is an array of booleans.
+              objectarray: Source value is an array of objects.
+              arrayarray: Source value is an array of arrays.
+            examples:
+              - string
+              - number
+              - boolean
+              - object
+          mappings:
+            type: array
+            description: |
+              **Purpose**
+              Enables recursive definition of nested object structures through child mapping objects.
+
+              **Guidance**
+              This is the KEY FIELD that implements the recursive pattern at the core of this schema:
+
+              **When to Use**
+              - REQUIRED when dataType = "object" (unless you are copying an entire object from the input record)
+              - REQUIRED in buildArrayHelper.mappings when defining complex object array elements
+              - NEVER used with simple types (string, number, boolean, date)
+
+              **Behavior**
+              - Each mapping in this array becomes a property of the parent object
+              - The full Mappings schema is repeated recursively at each level
+              - Can be nested to any depth for complex hierarchical structures
+
+              **Context Handling**
+              - Each level of nesting changes the mapping CONTEXT for 'generate'
+              - The extraction CONTEXT always remains the original input record
+              - This means child mappings can pull data from anywhere in the input record
+
+              **Common Patterns**
+
+              **Nested Objects**
+              ```json
+              {
+                "generate": "customer",
+                "dataType": "object",
+                "mappings": [
+                  {
+                    "generate": "contact",
+                    "dataType": "object",
+                    "mappings": [
+                      {"generate": "email", "dataType": "string", "extract": "$.customerEmail"}
+                    ]
+                  }
+                ]
+              }
+              ```
+
+              **Multiple Fields in Object**
+              ```json
+              {
+                "generate": "address",
+                "dataType": "object",
+                "mappings": [
+                  {"generate": "street", "dataType": "string", "extract": "$.address.line1"},
+                  {"generate": "city", "dataType": "string", "extract": "$.address.city"},
+                  {"generate": "country", "dataType": "string", "extract": "$.address.country"}
+                ]
+              }
+              ```
+
+              IMPORTANT: When analyzing or generating mappings, ALWAYS check if parent.dataType = "object"
+              or if you're inside buildArrayHelper.mappings for objectarray elements. These are the only
+              valid contexts for the mappings array.
+            items:
+              $ref: '#/components/schemas/items'
+            examples:
+              - - generate: firstName
+                  extract: $.name.first
+                  dataType: string
+                  status: Active
+                - generate: lastName
+                  extract: $.name.last
+                  dataType: string
+                  status: Active
+          buildArrayHelper:
+            type: array
+            x-celigo-ai-guidance:
+              - |-
+                Entry-level `extract` accepts an iterating array path
+                (`$.items[*]`), `"$"` (the record root), or omission — a
+                constructed entry (child `mappings` with the extract omitted or
+                `"$"`; the two spellings are equivalent) contributes exactly one
+                element, and entries append in order. Indexed or comma-joined
+                entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
+                processor renders the entire destination array as null with no
+                validation error. To emit a fixed number of static elements, add
+                that many sibling constructed entries — never index the extract.
+            description: |
+              **Purpose**
+              Configures how to construct arrays in the output record, handling various array types and inputs.
+
+              **Guidance**
+              This is the REQUIRED mechanism for ALL array data types:
+
+              **When to Use**
+              - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
+              - Each entry in this array contributes elements to the output array
+              - Multiple entries allow combining data from different input arrays
+
+              **Array Type Handling**
+
+              **For Simple Arrays (stringarray, numberarray, booleanarray)**
+              - Only the 'extract' field is used to pull values
+              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+              - Each result is converted to the appropriate primitive type
+              ```json
+              {
+                "generate": "productNames",
+                "dataType": "stringarray",
+                "buildArrayHelper": [
+                  {"extract": "$.products[*].name"}
+                ]
+              }
+              ```
+
+              **For Object Arrays (objectarray) - three patterns**
+
+              1. Extract Only (existing objects):
+              ```json
+              {
+                "generate": "contacts",
+                "dataType": "objectarray",
+                "buildArrayHelper": [
+                  {"extract": "$.account.primaryContacts[*]"},  // Pull primary contact objects
+                  {"extract": "$.account.secondaryContacts[*]"},  // Pull secondary contact objects
+                  {"extract": "$.vendor.contactPersons[*]"},  // Pull vendor contact objects
+                  {"extract": "$.subsidiaries[*].mainContact"}  // Pull main contact from each subsidiary
+                ]
+              }
+              ```
+
+              2. Mappings Only (constructed object):
+              ```json
+              {
+                "generate": "contactInfo",
+                "dataType": "objectarray",
+                "buildArrayHelper": [
+                  {
+                    "mappings": [  // Creates one object in the array
+                      {"generate": "type", "dataType": "string", "extract": "primary"},
+                      {"generate": "email", "dataType": "string", "extract": "$.primaryEmail"}
+                    ]
+                  },
+                  {
+                    "mappings": [  // Creates another object in the array
+                      {"generate": "type", "dataType": "string", "extract": "secondary"},
+                      {"generate": "email", "dataType": "string", "extract": "$.secondaryEmail"}
+                    ]
+                  }
+                ]
+              }
+              ```
+              Each constructed entry contributes exactly one element, in entry
+              order; writing the entry with `"extract": "$"` is equivalent to
+              omitting the extract (both anchor the element at the record root).
+              A fixed number of static elements is built from that many sibling
+              constructed entries.
+
+              3. Extract AND Mappings (transform input arrays):
+              ```json
+              {
+                "generate": "lineItems",
+                "dataType": "objectarray",
+                "buildArrayHelper": [
+                  {
+                    "extract": "$.order.items[*]",  // For each item in the array
+                    "mappings": [  // Transform to this structure using the composite object
+                      {"generate": "sku", "dataType": "string", "extract": "$.order.items.productId"},  // Notice: items is singular
+                      {"generate": "quantity", "dataType": "number", "extract": "$.order.items.qty"},   // Notice: items is singular
+                      {"generate": "orderNumber", "dataType": "string", "extract": "$.order.id"},       // Access parent data
+                      {"generate": "customerName", "dataType": "string", "extract": "$.customerName"}   // Access root data
+                    ]
+                  }
+                ]
+              }
+              ```
+
+              **For Arrays of Arrays (arrayarray)**
+              - Similar to objectarray, but inner arrays have empty 'generate' fields
+              - Used for matrix/table structures
+              ```json
+              {
+                "generate": "matrix",
+                "dataType": "arrayarray",
+                "buildArrayHelper": [
+                  {
+                    "extract": "$.rows[*]",  // For each row in the rows array
+                    "mappings": [
+                      {
+                        "dataType": "numberarray",  // Note: No generate field for inner arrays
+                        "buildArrayHelper": [
+                          {"extract": "$.rows.columns[*]"}  // Notice: "rows" is singular in the composite object
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              }
+              ```
+
+              **Important details**
+
+              - When both extract and mappings are provided, the system creates special composite objects
+                that maintain hierarchical context during processing
+              - This enables accessing both the current array element AND its parent context
+              - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
+                (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
+                instead omits extract or sets it to exactly "$" — never rewrite "$" into a
+                '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
+                the entire destination array as null without raising a validation error
+              - Each array helper entry acts independently, potentially adding multiple elements
+
+              The buildArrayHelper is the most complex part of the mappings system - always analyze the
+              dataType first to understand which pattern is appropriate.
+            items:
+              type: object
+              properties:
+                extract:
+                  type: string
+                  description: |
+                    JSON path expression that identifies the input array or values to extract.
+
+                    For objectarray with mappings, this defines which input objects to iterate through.
+                    The JSON path must return either a single object or an array of objects.
+
+                    For a CONSTRUCTED entry (child mappings building exactly one element from
+                    record-root fields and constants), omit this field or set it to exactly "$" —
+                    the two spellings are equivalent. Indexed or comma-joined forms ('$[0]',
+                    '$[0],$[0]') are not valid at the entry level: the processor renders the
+                    entire destination array as null without raising a validation error.
+
+                    The system creates special composite objects during processing to maintain
+                    hierarchical relationships, allowing easy access to both the current array item
+                    and its parent contexts.
+                  examples:
+                    - $.items[*]
+                    - $.order.lineItems[*]
+                    - $.parents[*].children[*]
+                    - $
+                sourceDataType:
+                  type: string
+                  description: |
+                    Declares the JSON type of the input array being iterated, to ensure
+                    proper type handling during array construction. Same enum as `dataType`.
+                  enum:
+                    - string
+                    - number
+                    - boolean
+                    - object
+                    - stringarray
+                    - numberarray
+                    - booleanarray
+                    - objectarray
+                    - arrayarray
+                  x-enumDescriptions:
+                    string: Input array contains string elements.
+                    number: Input array contains numeric elements.
+                    boolean: Input array contains boolean elements.
+                    object: Input array contains object elements.
+                    stringarray: Input array contains arrays of strings.
+                    numberarray: Input array contains arrays of numbers.
+                    booleanarray: Input array contains arrays of booleans.
+                    objectarray: Input array contains arrays of objects.
+                    arrayarray: Input array contains arrays of arrays.
+                  examples:
+                    - string
+                    - number
+                    - boolean
+                    - object
+                default:
+                  type:
+                    - string
+                    - 'null'
+                  description: |
+                    Specifies a fallback value when the extracted array element is empty or
+                    not found in the input data.
+
+                    Explicit JSON `null` is itself a valid fallback (the element is written as
+                    JSON null); omitting the key means no fallback is applied.
+                  examples:
+                    - N/A
+                    - '0'
+                    - 'false'
+                conditional:
+                  type: object
+                  description: |
+                    Defines conditional rules for including each array element in the result.
+                  properties:
+                    when:
+                      type: string
+                      description: |
+                        Specifies the condition that must be met for an array element to be included.
+
+                        'extract_not_empty' only includes elements where the extract field returns a value.
+                      enum:
+                        - extract_not_empty
+                      x-enumDescriptions:
+                        extract_not_empty: Include the array element only when the extract field returns a non-empty value.
+                      examples:
+                        - extract_not_empty
+                mappings:
+                  type: array
+                  description: |
+                    Contains recursive mapping definitions for complex array element transformations.
+
+                    **Composite object mechanism**
+
+                    When both 'extract' and 'mappings' are used together, the system implements a sophisticated
+                    "composite object" approach that is crucial for AI agents to understand:
+
+                    1. The system starts with the complete input record
+
+                    2. For each array element matched by the extract path, it creates a modified version of
+                       the input record where:
+                       - Array paths in the extract JSON path are REPLACED with single objects
+                       - Each array ([]) in the path is converted to a single object ({})
+                       - This preserves the hierarchical relationship between nested arrays
+
+                    **Example**
+
+                    Given an input record:
+                    ```json
+                    {
+                      "customer": {
+                        "name": "John Doe",
+                        "orders": [
+                          {
+                            "id": "O-001",
+                            "items": [
+                              {"sku": "ABC", "qty": 2},
+                              {"sku": "XYZ", "qty": 1}
+                            ]
+                          },
+                          {
+                            "id": "O-002",
+                            "items": [
+                              {"sku": "DEF", "qty": 3}
+                            ]
+                          }
+                        ]
+                      }
+                    }
+                    ```
+
+                    With extract path: `$.customer.orders[*].items[*]`
+
+                    For each item, the system creates a composite object like:
+                    ```json
+                    {
+                      "customer": {
+                        "name": "John Doe",
+                        "orders": {  // Note: Array replaced with single object
+                          "id": "O-001",
+                          "items": {  // Note: Array replaced with single object
+                            "sku": "ABC",
+                            "qty": 2
+                          }
+                        }
+                      }
+                    }
+                    ```
+
+                    Then in your mappings, you can access:
+                    - The current item: `$.customer.orders.items.sku`
+                    - The parent order: `$.customer.orders.id`
+                    - Top-level data: `$.customer.name`
+
+                    This approach allows for precise mapping from deeply nested structures while maintaining
+                    access to all contextual parent data, without requiring complex array index management.
+
+                    **Implementation guidance**
+
+                    When implementing the composite object mechanism:
+
+                    1. Analyze the extract path to identify all array patterns (`[*]` or `[number]`)
+                    2. For each array in the path, understand that it will be replaced with a single object
+                    3. In the mappings, use paths that reference these arrays as if they were objects
+                    4. Remember that every mapping still has access to the full input record context
+                    5. This mechanism is especially powerful when mapping hierarchical data like:
+                       - Order → Line Items → Taxes/Discounts
+                       - Customer → Addresses → Address Lines
+                       - Invoice → Line Items → Serial Numbers
+
+                    The extract path effectively tells the system "iterate through these arrays",
+                    while the composite object mechanism ensures you can still access both the
+                    current array item AND its parent context during mapping.
+                  items:
+                    $ref: '#/components/schemas/items'
+                  examples:
+                    - - generate: itemName
+                        extract: $.name
+                        dataType: string
+                        status: Active
+                      - generate: itemPrice
+                        extract: $.price
+                        dataType: number
+                        status: Active
+          status:
+            type: string
+            description: |
+              **Purpose**
+              Required on every mapping entry. Controls whether the mapping is applied.
+
+              **Guidance**
+              Emit `"Active"` for mappings that should run; `"Draft"` saves an
+              in-progress mapping without the Active-only field validations. The
+              API rejects a mapping missing this field
+              (validation error: "Mapping object must have status field present.").
+            x-celigo-ai-guidance:
+              - |-
+                Emit `"Active"` for mappings that should run; `"Draft"` is also
+                accepted and saves the mapping while bypassing the Active-only
+                field validations. The value is case-sensitive. The API rejects:
+                - Missing field: `[status_field_absent] Mapping object must have status field present.`
+                - Wrong case (e.g. `"active"`): `[invalid_status_enums] active is not a valid enum for status field.`
+            enum:
+              - Active
+              - Draft
+            x-enumDescriptions:
+              Active: The mapping is enabled and applied during processing.
+              Draft: In-progress mapping; saved without the Active-only field validations.
+            examples:
+              - Active
+          conditional:
+            type: object
+            description: |
+              **Purpose**
+              Defines conditional processing rules for the entire mapping.
+
+              **Guidance**
+              These conditions determine whether the mapping is applied based on record
+              state or field content:
+
+              **When to Use**
+              - When a mapping should only be applied in specific circumstances
+              - To implement conditional logic without using complex handlebars expressions
+              - For creating mappings that only run during create or update operations
+
+              **Available Conditions**
+
+              - `record_created`: Apply only when creating a new record
+                Useful for setting initial values that should not be overwritten during updates
+
+              - `record_updated`: Apply only when updating an existing record
+                Useful for transformation logic that should only run during updates
+
+              - `extract_not_empty`: Apply only when the extract field returns a value
+                Useful for conditional mapping based on input data availability
+
+              **Example**
+              ```json
+              {
+                "generate": "statusMessage",
+                "dataType": "string",
+                "status": "Active",
+                "extract": "$.status.message",
+                "conditional": {
+                  "when": "extract_not_empty"  // Only map when status.message exists
+                }
+              }
+              ```
+            properties:
+              when:
+                type: string
+                description: |
+                  Specifies the condition that triggers application of this mapping:
+                  - record_created: Apply only when creating a new record
+                  - record_updated: Apply only when updating an existing record
+                  - extract_not_empty: Apply only when the extract field returns a value
+                enum:
+                  - record_created
+                  - record_updated
+                  - extract_not_empty
+                x-enumDescriptions:
+                  record_created: Apply this mapping only when creating a new record.
+                  record_updated: Apply this mapping only when updating an existing record.
+                  extract_not_empty: Apply this mapping only when the extract field returns a non-empty value.
+                examples:
+                  - record_created
+                  - record_updated
+                  - extract_not_empty
+        required:
+          - dataType
+    Lookups:
+      type: array
+      description: |
+        Configuration for value-to-value transformations using lookup tables.
+
+        **Purpose**
+
+        Lookups provide a way to translate values from one system to another. They transform
+        input values into output values using either static mapping tables or
+        dynamic lookup caches.
+
+        **Lookup mechanisms**
+
+        There are two distinct lookup mechanisms available:
+
+        1. **Static Lookups**: Define a simple key-value map object and store it as part of your resource
+           - Best for: Small, fixed sets of values that rarely change
+           - Implementation: Configure the `map` object with input-to-output value mappings
+           - Example: Country codes, status values, simple translations
+
+        2. **Dynamic Lookups**: Reference an existing 'Lookup Cache' resource in your Celigo account
+           - Best for: Large datasets, frequently changing values, or complex reference data
+           - Implementation: Configure `_lookupCacheId` to reference cached data maintained independently
+           - Example: Product catalogs, customer databases, pricing information
+
+        **Property usage**
+
+        There are two mutually exclusive ways to configure lookups, depending on which mechanism you choose:
+
+        1. **For Static Mappings**: Configure the `map` property with a direct key-value object
+           ```json
+           "map": {"US": "United States", "CA": "Canada"}
+           ```
+
+        2. **For Dynamic Lookups**: Configure the following properties:
+           - `_lookupCacheId`: Reference to the lookup cache resource
+           - `extract`: JSON path to extract specific value from the returned lookup object
+
+        **When to use**
+
+        Lookups are ideal for:
+
+        1. **Value Translation**: Mapping codes or IDs to human-readable values
+
+        2. **Data Enrichment**: Adding related information to records during processing
+
+        3. **Normalization**: Ensuring consistent formatting of values across systems
+
+        **Implementation details**
+
+        Lookups can be referenced in:
+
+        1. **Field Mappings**: Direct use in field transformation configurations
+
+        2. **Handlebars Templates**: Use within templates with the syntax:
+           ```
+           {{lookup 'lookupName' record.fieldName}}
+           ```
+
+        **Example usage**
+
+        ```json
+        "lookups": [
+          {
+            "name": "countryCodeToName",
+            "map": {
+              "US": "United States",
+              "CA": "Canada",
+              "UK": "United Kingdom"
+            },
+            "default": "Unknown Country",
+            "allowFailures": true
+          },
+          {
+            "name": "productDetails",
+            "_lookupCacheId": "60a2c4e6f321d800129a1a3c",
+            "extract": "$.details.price",
+            "allowFailures": false
+          }
+        ]
+        ```
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            description: |
+              Unique identifier for the lookup table within this configuration.
+
+              This name must be unique within the scope where the lookup is defined and is used to reference
+              the lookup in handlebars templates with the syntax {{lookup 'name' value}}.
+
+              Choose descriptive names that indicate the transformation purpose, such as:
+              - "countryCodeToName" for country code to full name conversion
+              - "statusMapping" for status code translations
+              - "departmentCodes" for department code to name mapping
+            examples:
+              - countryCodeToName
+              - statusMapping
+              - departmentCodes
+          map:
+            type:
+              - object
+              - 'null'
+            description: |
+              The lookup mapping table as key-value pairs. The platform stores `null`
+              here on dynamic lookups, which resolve values at runtime instead of
+              from a static table.
+
+              This object contains the input values as keys and their corresponding
+              output values. When a input value matches a key in this object,
+              it will be replaced with the corresponding value.
+
+              The map should be kept to a reasonable size (typically under 100 entries)
+              for optimal performance. For larger mapping requirements, consider using
+              dynamic lookups instead.
+
+              Maps can include:
+              - Simple code to name conversions: {"US": "United States"}
+              - Status transformations: {"A": "Active", "I": "Inactive"}
+              - ID to name mappings: {"100": "Marketing", "200": "Sales"}
+
+              Values can be strings, numbers, or booleans, but all are stored as strings
+              in the configuration.
+            examples:
+              - US: United States
+                UK: United Kingdom
+                CA: Canada
+              - A: Active
+                I: Inactive
+                P: Pending
+              - 'true': 'Yes'
+                'false': 'No'
+          _lookupCacheId:
+            type: string
+            description: |
+              Reference to a LookupCache resource that contains the reference data for the lookup.
+
+              **Purpose**
+
+              This field connects the lookup to an external data source that has been cached in the system.
+              Unlike static lookups that use the `map` property, dynamic lookups can reference large datasets
+              or frequently changing information without requiring constant updates to the integration.
+
+              **Implementation details**
+
+              The LookupCache resource referenced by this ID contains:
+              - The data records to be used as a reference source
+              - Configuration for how the data should be indexed and accessed
+              - Caching parameters to balance performance with data freshness
+
+              **Usage patterns**
+
+              Commonly used to reference:
+              - Product catalogs or SKU databases
+              - Customer or account information
+              - Pricing tables or discount rules
+              - Complex business logic lookup tables
+
+              Format: 24-character hexadecimal string (MongoDB ObjectId)
+            format: objectid
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 60a2c4e6f321d800129a1a3c
+              - 5f8d43a1b9e5a80011a35f2c
+          extract:
+            type: string
+            description: |
+              JSON path expression that extracts a specific value from the cached lookup object.
+
+              **Purpose**
+
+              When using dynamic lookups with a LookupCache, this JSON path identifies which field to extract
+              from the cached object after it has been retrieved using the lookup key.
+
+              **Implementation details**
+
+              - Must use JSON path syntax (similar to mapping extract fields)
+              - Operates on the cached object returned by the lookup operation
+              - Examples:
+                - "$.name" - Extract the name field from the top level
+                - "$.details.price" - Extract a nested price field
+                - "$.attributes[0].value" - Extract a value from the first element of an array
+
+              **Usage scenario**
+
+              When a lookup cache contains complex objects:
+              ```json
+              // Cache entry for key "PROD-123":
+              {
+                "id": "PROD-123",
+                "name": "Premium Widget",
+                "details": {
+                  "price": 99.99,
+                  "currency": "USD",
+                  "inStock": true
+                }
+              }
+              ```
+
+              Setting extract to "$.details.price" would return 99.99 as the lookup result.
+
+              If no extract is provided, the entire cached object is returned as the lookup result.
+            examples:
+              - $.name
+              - $.details.price
+              - $.attributes.color
+              - $.category.name
+          default:
+            type:
+              - string
+              - 'null'
+            description: |
+              Default value to use when the source value is not found in the lookup map.
+              The platform stores `null` here when no default is configured.
+
+              This value is used as a fallback when:
+              1. The source value doesn't match any key in the map
+              2. allowFailures is set to true
+
+              Setting an appropriate default helps prevent flow failures due to unexpected
+              values and provides predictable behavior for edge cases.
+
+              Common default patterns include:
+              - Descriptive unknowns: "Unknown Country", "Unspecified Status"
+              - Original value indicators: "{Original Value}", "No mapping found"
+              - Neutral values: "Other", "N/A", "Miscellaneous"
+
+              If allowFailures is false and no default is specified, the flow will fail
+              when encountering unmapped values.
+            examples:
+              - Unknown
+              - Other
+              - N/A
+              - Unmapped Value
+              - '{Original Value}'
+            x-celigo-ai-guidance:
+              - 'Omit this field entirely when no fallback value is intended. The API rejects an empty string with [invalid_field] Invalid value '''' for field ''default'' — emitting default: "" to mean "no default" fails validation; leaving the key out is the valid spelling of that intent.'
+          allowFailures:
+            type:
+              - boolean
+              - 'null'
+            description: |
+              When true, missing lookup values will use the default value rather than causing an error.
+
+              **Behavior control**
+
+              This field determines how the system handles source values that don't exist in the map:
+
+              - true: Use the default value for missing mappings and continue processing
+              - false: Treat missing mappings as errors, failing the record
+
+              **Recommendation**
+
+              Set this to true when:
+              - New source values might appear over time
+              - Data quality issues could introduce unexpected values
+              - Processing should continue even with imperfect mapping
+
+              Set this to false when:
+              - Complete data accuracy is critical
+              - All possible source values are known and controlled
+              - Missing mappings indicate serious data problems that should be addressed
+
+              The best practice is typically to set allowFailures to true with a meaningful
+              default value, so flows remain operational while alerting you to missing mappings.
+            examples:
+              - true
+              - false
+    Transform:
+      type: object
+      description: |
+        Configuration for transforming data during processing operations. This object enables
+        reshaping of records.
+
+        **Transformation capabilities**
+
+        Celigo's transformation engine offers powerful features for data manipulation:
+        - Precise field mapping with JSONPath expressions
+        - Support for any level of nested arrays
+        - Formula-based field value generation
+        - Dynamic references to flow and integration settings
+
+        **Implementation approaches**
+
+        There are two distinct transformation mechanisms available:
+
+        **Rule-Based Transformation (`type: "expression"`)**
+        - **Best For**: Most transformation scenarios from simple to complex
+        - **Capabilities**: Field mapping, formula calculations, lookups, nested data handling
+        - **Advantages**: Visual configuration, no coding required, intuitive interface
+        - **Configuration**: Define rules in the `expression` object
+        - **Use When**: You have clear mapping requirements or need to reshape data structure
+
+        **Script-Based Transformation (`type: "script"`)**
+        - **Best For**: Extremely complex logic or proprietary algorithms
+        - **Capabilities**: Full programmatic control, custom processing, complex business rules
+        - **Advantages**: Maximum flexibility, can implement any transformation logic
+        - **Configuration**: Reference a script in the `script` object
+        - **Use When**: Visual transformation tools aren't sufficient for your use case
+      properties:
+        type:
+          type: string
+          description: |
+            Determines which transformation mechanism to use. This choice affects which properties
+            must be configured and how transformation logic is implemented.
+
+            **Available types**
+
+            **Rule-Based Transformation (`"expression"`)**
+            - **Required Config**: The `expression` object with mapping definitions
+            - **Behavior**: Applies declarative rules to reshape data
+            - **Best For**: Most transformation scenarios from simple to complex
+            - **Advantages**: Visual configuration, no coding required
+
+            **Script-Based Transformation (`"script"`)**
+            - **Required Config**: The `script` object with _scriptId and function
+            - **Behavior**: Executes custom JavaScript to transform data
+            - **Best For**: Extremely complex logic or proprietary algorithms
+            - **Advantages**: Maximum flexibility, can implement any logic
+
+            **Implementation guidance**
+
+            1. For standard data transformations, use `"expression"`
+            2. For complex logic or specialized processing, use `"script"`
+            3. When selecting a type, you must configure the corresponding object:
+                - `type: "expression"` requires the `expression` object
+                - `type: "script"` requires the `script` object
+          enum:
+            - expression
+            - script
+          x-enumDescriptions:
+            expression: Rule-based transformation using declarative mapping definitions.
+            script: Script-based transformation using custom JavaScript logic.
+          examples:
+            - expression
+            - script
+        expression:
+          type: object
+          description: |
+            Configuration for declarative rule-based transformations. This object enables reshaping data
+            without requiring custom code.
+
+            **Usage context**
+
+            This object is REQUIRED when `transform.type` is set to "expression" and should not be
+            configured otherwise. It provides a standardized way to define transformation rules that
+            can map, modify, and generate data elements.
+
+            **Implementation guidance**
+
+            The expression system uses a rule-based approach where:
+            - Field mappings define how input data is transformed to target fields
+            - Formulas can be used to calculate or generate new values
+            - Lookups can enrich data by fetching related information
+            - Mode determines how records are processed (create new or modify existing)
+          properties:
+            version:
+              type: string
+              description: |
+                Version of the expression format. Determines which rules
+                property contains the transformation logic.
+              enum:
+                - '1'
+                - '2'
+              x-enumDescriptions:
+                '1': Legacy format. Rules are in the `rules` array (array of arrays of extract/generate objects).
+                '2': Current format. Rules are in the `rulesTwoDotZero` object with mode, mappings, and lookups.
+              examples:
+                - '1'
+                - '2'
+            rules:
+              type: array
+              description: |
+                Transformation rules for version 1 expressions. An array of
+                rule groups; each group is an array of field-mapping objects.
+                Most transforms have a single group. Present when `version`
+                is `"1"`. The output record contains ONLY the generated
+                fields — every unmapped field is dropped (v1 has no
+                equivalent of Transform 2.0's `modify` mode), and the
+                record's trace key does not survive the rebuild.
+              x-celigo-ai-guidance:
+                - |-
+                  v1 rules REPLACE the record: a one-field rule group drops
+                  every other field, silently breaking downstream filters,
+                  router branch rules, and templates that referenced the
+                  dropped fields. Either map every field downstream logic
+                  needs forward, or author Transform 2.0 with
+                  ``mode: "modify"`` instead.
+              items:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    extract:
+                      type: string
+                      description: |
+                        Source field path to read from. Supports multiple
+                        syntaxes: bare field names (`id`), dot notation
+                        (`fulfillment.shipment_id`), slash-prefixed paths
+                        for XML (`/FeedProcessingStatus`), wildcards (`*.id`,
+                        `*.[Internal ID]`), and array indexing (`SDF[0]`).
+                    generate:
+                      type: string
+                      description: |
+                        Target field name to write to. Typically a bare name
+                        (`id`) or dot path (`SDF.Filter.ID`).
+                    key:
+                      type: string
+                      description: |
+                        Auto-generated identifier for this rule, used by the
+                        UI to track individual rules for editing and reordering.
+                  required:
+                    - extract
+                    - generate
+            rulesTwoDotZero:
+              type: object
+              description: |
+                Configuration for version 2 transformation rules. This object contains the core logic
+                for how data is mapped, enriched, and transformed.
+
+                **Capabilities**
+
+                Transformation 2.0 provides:
+                - Precise field mapping with JSONPath expressions
+                - Support for deeply nested data structures
+                - Formula-based field generation
+                - Dynamic lookups for data enrichment
+                - Multiple operating modes to fit different scenarios
+              properties:
+                mode:
+                  type: string
+                  description: |
+                    Transformation mode that determines how records are handled during processing.
+
+                    **Available modes**
+
+                    **Create Mode (`"create"`)**
+                    - **Behavior**: Builds entirely new output records from inputs
+                    - **Use When**: Output structure differs significantly from input
+                    - **Advantage**: Clean slate approach, no field inheritance
+
+                    **Modify Mode (`"modify"`)**
+                    - **Behavior**: Makes targeted edits to existing records
+                    - **Use When**: Output structure should remain similar to input
+                    - **Advantage**: Preserves unmapped fields from the original record
+                  enum:
+                    - create
+                    - modify
+                  x-enumDescriptions:
+                    create: Builds entirely new output records from inputs, ignoring unmapped fields.
+                    modify: Makes targeted edits to existing records, preserving unmapped fields.
+                  examples:
+                    - create
+                    - modify
+                mappings:
+                  $ref: '#/components/schemas/Mappings'
+                lookups:
+                  allOf:
+                    - description: |
+                        Shared lookup tables used across all mappings defined in the transformation rules.
+
+                        **Purpose**
+
+                        Lookups provide centralized value translation that can be referenced from any mapping
+                        in your transformation configuration. They enable consistent translation of codes, IDs,
+                        and values between systems without duplicating translation logic.
+
+                        **Usage in transformations**
+
+                        Lookups are particularly valuable in transformations for:
+
+                        - **Data Normalization**: Standardizing values from diverse source systems
+                        - **Code Translation**: Converting between different coding systems (e.g., status codes)
+                        - **Field Enrichment**: Adding descriptive values based on ID or code lookups
+                        - **Cross-Reference Resolution**: Mapping identifiers between integrated systems
+
+                        **Implementation**
+
+                        Lookups are defined once in this array and referenced by name in mappings:
+
+                        ```json
+                        "lookups": [
+                          {
+                            "name": "statusMapping",
+                            "map": {
+                              "A": "Active",
+                              "I": "Inactive",
+                              "P": "Pending"
+                            },
+                            "default": "Unknown Status"
+                          }
+                        ]
+                        ```
+
+                        Then referenced in mappings using the lookupName property:
+
+                        ```json
+                        {
+                          "generate": "status",
+                          "dataType": "string",
+                          "extract": "$.statusCode",
+                          "lookupName": "statusMapping"
+                        }
+                        ```
+
+                        The system automatically applies the lookup during transformation processing.
+
+                        For complete details on lookup properties and behavior, see the Lookups schema.
+                    - $ref: '#/components/schemas/Lookups'
+                inputContext:
+                  type: string
+                  enum:
+                    - record
+                    - envelope
+                  x-enumDescriptions:
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, settings, job, …}` (file-provider steps also carry `fileMeta`) — extracts must include the `record.` segment (`$.record.field`).
+                  description: |
+                    Controls the JSON shape the transformTwoDotZero processor
+                    evaluates `mappings[].extract` JSONPath values against at
+                    flow runtime. Applies only to Transform 2.0 (v2,
+                    `rulesTwoDotZero`); v1 transforms (the `rules` array on
+                    `transform.expression.rules`) and script-mode transforms
+                    ignore this field.
+                  x-celigo-ai-guidance:
+                    - |-
+                      ## Extract anchoring by mode
+
+                      - `record` (default — absent / empty / undefined): the
+                        processor sees the FLAT record as its evaluation root.
+                        `mappings[].extract` JSONPath MUST anchor directly at
+                        `$` with NO `record.` segment — e.g. `"$.orderId"`,
+                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.PLACEHOLDER_<field>"`.
+                        This is the dominant Celigo idiom and the right choice for new transforms.
+                      - `envelope`: the processor sees a wrapped object
+                        `{record: {...}, settings: ..., job: ...}` (plus
+                        `fileMeta` on file-provider steps).
+                        `mappings[].extract` JSONPath MUST include the
+                        `record.` segment — e.g. `"$.record.orderId"`;
+                        PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
+                        Pick this only when the transform was authored against
+                        the envelope shape on purpose.
+                    - |-
+                      Handlebars expressions inside `extract`
+                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
+                      ALWAYS reference the `record` root regardless of
+                      `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      Emit `inputContext` explicitly on new v2 transforms:
+                      unset is read as `record`, but stating it makes the
+                      extract-anchoring contract self-documenting and immune
+                      to a platform default change.
+                    - |-
+                      ## Allowed values
+
+                      - ``record`` (default — emitted when the field is absent
+                        / empty / undefined): the transform processor sees
+                        the FLAT record itself as its evaluation root.
+                        ``mappings[].extract`` JSONPath values MUST anchor
+                        directly at ``$`` with NO ``record.`` segment — for
+                        example ``"$.orderId"`` or
+                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.PLACEHOLDER_<field>"``.  This is the dominant
+                        Celigo idiom and the right choice for new transforms.
+
+                      - ``envelope``: the transform processor sees a wrapped
+                        object of the shape
+                        ``{record: {...}, settings: ..., job: ...}`` (plus
+                        ``fileMeta`` on file-provider steps) — the
+                        same runtime-context envelope Handlebars / SQL /
+                        GraphQL specialists consume.  ``mappings[].extract``
+                        JSONPath values MUST include the ``record.`` segment
+                        — for example ``"$.record.orderId"`` or
+                        ``"$.record.customer.email"``.  PLACEHOLDER extracts
+                        use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
+                        mode only when the export was authored against the
+                        envelope shape on purpose (typically because an
+                        upstream step intentionally feeds the wrapped
+                        runtime context through to the transform).
+
+                      ## Handlebars expressions are NOT affected
+
+                      Handlebars expressions inside ``extract``
+                      (``{{record.field}}``,
+                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
+                      reference the runtime context's ``record`` root
+                      regardless of ``inputContext`` — the Handlebars runtime
+                      always sees the wrapped envelope.  Only JSONPath
+                      behavior flips with this field.
+
+                      ## Agent guidance
+
+                      Set this field explicitly on every new v2 transform
+                      the agent authors.  Leaving it unset is interpreted as
+                      ``record`` by the platform, but emitting
+                      ``inputContext: record`` makes the contract
+                      self-documenting and prevents the transform from
+                      drifting into envelope mode if an upstream change ever
+                      changes the platform default.  The TransformsAgent
+                      reads this value off the transform config and threads
+                      it into the generator's prompt so the JSONPath form
+                      matches the runtime root.
+                    - |-
+                      ## fileMeta on file-provider steps
+
+                      File-provider exports and lookups populate a
+                      ``fileMeta`` envelope key describing each record's
+                      source file: ``fileName``, ``fileSize``, and
+                      ``lastModifiedTime`` (epoch milliseconds).  Reach it
+                      as ``$.fileMeta.<field>`` in envelope mode, or as
+                      ``{{fileMeta.<field>}}`` from a Handlebars extract in
+                      either mode.  The keys are exactly these three —
+                      lowercase variants such as ``filesize`` or
+                      ``filename`` resolve empty.  The standalone transform
+                      processor substitutes sample fileMeta values when the
+                      posted data lacks them, so a resolving editor render
+                      is not proof the step provides fileMeta — only
+                      file-provider steps populate it at flow runtime.
+                  examples:
+                    - record
+                    - envelope
+        script:
+          type: object
+          description: |
+            Configuration for programmable script-based transformations. This object enables complex, custom
+            transformation logic beyond what expression-based transformations can provide.
+
+            **Usage context**
+
+            This object is REQUIRED when `transform.type` is set to "script" and should not be configured
+            otherwise. It provides a way to execute custom JavaScript code to transform data according to
+            specialized business rules or complex algorithms.
+
+            **Implementation approach**
+
+            Script-based transformation works by:
+            1. Executing the specified function from the referenced script
+            2. Passing input data to the function
+            3. Using the function's return value as the transformed output
+
+            **Common use cases**
+
+            Script transformation is ideal for:
+            - Complex business logic that can't be expressed through mappings
+            - Algorithmic transformations requiring computation
+            - Dynamic transformations based on external factors
+            - Legacy system data format compatibility
+            - Multi-stage processing with intermediate steps
+
+            Only use script-based transformation when expression-based transformation is insufficient.
+            Script transformation requires maintaining custom code, which adds complexity to the integration.
+          properties:
+            _scriptId:
+              type: string
+              description: |
+                Reference to a predefined script resource containing the transformation logic.
+
+                The referenced script should contain the function specified in the
+                'function' property.
+              format: objectid
+              x-celigo-refModel: scripts
+              examples:
+                - 60a2c4e6f321d800129a1a3c
+                - 5f8d43a1b9e5a80011a35f2c
+            function:
+              type: string
+              description: |
+                Name of the function within the script to execute for transformation. This function
+                must exist in the script referenced by _scriptId.
+              examples:
+                - transformData
+                - convertRecord
+                - applyMapping
+    AsyncHelperBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          description: Human-readable name for the async helper.
+          examples:
+            - Salesforce Bulk Query Helper
+        externalId:
+          type: string
+          description: |
+            External identifier for the async helper. Used by integration apps
+            to reference resources by a stable, human-readable key.
+          examples:
+            - amazon_csv_feed_asynchelper
+        http:
+          type: object
+          description: |
+            HTTP configuration for the three async phases: submit, status, and
+            result.
+          properties:
+            submit:
+              type: object
+              description: Configuration for submitting the initial async request.
+              properties:
+                sameAsStatus:
+                  type: boolean
+                  description: |
+                    When `true`, the submit step reuses the status export's
+                    configuration. When `false`, configure `resourcePath`
+                    and optionally `transform`.
+                  examples:
+                    - true
+                  x-celigo-ai-guidance:
+                    - |-
+                      When true, reuse the status export's parsing rules for the
+                      initial submission response and ignore `resourcePath` /
+                      `transform`.
+                resourcePath:
+                  type: string
+                  description: |
+                    Path to extract the async job identifier from the submit
+                    response. Only used when `sameAsStatus` is `false`.
+                  examples:
+                    - id
+                  x-celigo-ai-guidance:
+                    - |-
+                      JSON/XML path to the data in the initial submission response
+                      (used only when `sameAsStatus` is false). Handlebars
+                      expressions may reference values from the status and result
+                      messages.
+                transform:
+                  $ref: '#/components/schemas/Transform'
+                  x-celigo-ai-guidance:
+                    - |-
+                      Optional transform rules applied to the initial submission
+                      response. Use when the asynchronous API returns non-JSON
+                      (e.g. XML from Amazon) that must be converted to JSON before
+                      `resourcePath` can extract from it. This is the rules-based
+                      (v1) transform shape.
+              required:
+                - sameAsStatus
+              x-celigo-ai-guidance:
+                - |-
+                  How to process the initial asynchronous request's response.
+                  Optional — omit (or set `sameAsStatus: true`) when the initial
+                  response is parsed the same way as a status check.
+                - |-
+                  Optional. When the initial response looks identical to a status
+                  check response, set `sameAsStatus: true` and the platform reuses
+                  the status export's parsing rules. Otherwise supply `resourcePath`
+                  (and `transform` for non-JSON responses) so the platform can pull
+                  the job ticket / feed id out of the acknowledgement.
+            status:
+              type: object
+              description: Configuration for polling the remote job's status.
+              properties:
+                _exportId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: exports
+                  description: Export resource ID for the status polling call.
+                  examples:
+                    - 63b1c2d3e4f5a60011334455
+                  x-celigo-ai-guidance:
+                    - |-
+                      Required. The export resource the platform runs on each poll
+                      to check whether the requested task is done. Must be an
+                      ordinary export that does not itself reference an async helper.
+                statusPath:
+                  type: string
+                  minLength: 1
+                  description: Path to extract the status value from the poll response.
+                  examples:
+                    - status
+                  x-celigo-ai-guidance:
+                    - |-
+                      Required. The XML/JSON path in the status response where the
+                      in-progress / done / error value appears (applied to records
+                      from the status export). For example `FeedProcessingStatus`.
+                initialWaitTime:
+                  type:
+                    - number
+                    - 'null'
+                  minimum: 0
+                  description: |
+                    Seconds to wait before the first status poll. May be fractional
+                    for sub-second waits; stored as null when unset.
+                  examples:
+                    - 1
+                pollWaitTime:
+                  type:
+                    - number
+                    - 'null'
+                  minimum: 0
+                  description: |
+                    Seconds to wait between subsequent status poll requests. May be
+                    fractional for sub-second polling; stored as null when unset.
+                  examples:
+                    - 4
+                inProgressValues:
+                  type: array
+                  description: |
+                    Values indicating the remote job is still running, so polling
+                    continues until the status matches one of the terminal lists.
+                  items:
+                    type: string
+                  examples:
+                    - - InProgress
+                      - Pending
+                doneValues:
+                  type: array
+                  minItems: 1
+                  description: Values indicating the remote job completed successfully.
+                  items:
+                    type: string
+                  examples:
+                    - - Completed
+                      - Done
+                doneWithoutDataValues:
+                  type: array
+                  description: Values indicating completion with no data. Optional.
+                  items:
+                    type: string
+                errorValues:
+                  type: array
+                  description: Values indicating the remote job failed. Optional.
+                  items:
+                    type: string
+              required:
+                - _exportId
+                - statusPath
+                - inProgressValues
+                - doneValues
+              x-celigo-ai-guidance:
+                - |-
+                  How the platform checks whether the background job is finished.
+                  On each poll it runs the status export and inspects the response
+                  at `statusPath` against the configured value lists.
+            result:
+              type: object
+              description: |
+                Configuration for retrieving the result. Omit `_exportId` to use
+                the last status poll response as the result.
+              properties:
+                _exportId:
+                  type:
+                    - string
+                    - 'null'
+                  format: objectId
+                  x-celigo-refModel: exports
+                  description: |
+                    Export resource ID for retrieving the result. Optional; null (or
+                    omitted) means the last status poll response is used as the result.
+                  examples:
+                    - 63c1d2e3f4a5b60011445566
+                  x-celigo-ai-guidance:
+                    - |-
+                      The export resource that retrieves the final results of the
+                      originally requested task. Must be an ordinary export that
+                      does not itself reference an async helper. Note: an export
+                      configured with an async helper cannot carry its own
+                      transforms, output filters, or preSavePage hooks — build
+                      those into a dedicated result export instead.
+          required:
+            - submit
+            - status
+          x-celigo-ai-guidance:
+            - |-
+              The async-API contract: how to interpret the initial submission
+              response, how to poll for status, and where to fetch results.
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    IAResourceResponse:
+      type: object
+      description: Integration app response fields for resources that are part of integration apps
+      properties:
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          readOnly: true
+          description: |
+            Reference to the specific integration instance that contains this resource.
+
+            This field is only populated for resources that are part of an integration app
+            installation. It contains the unique identifier (_id) of the integration
+            resource that was installed in the account.
+
+            The integration instance represents a specific installed instance of an
+            integration app, with its own configuration, settings, and runtime environment.
+
+            This reference enables:
+            - Tracing the resource back to its parent integration instance
+            - Permission and access control based on integration ownership
+            - Lifecycle management (enabling/disabling, updating, or uninstalling)
+          examples:
+            - 5f9a7b2c3d4e5f6a7b8c9d0e
+        _connectorId:
+          type: string
+          format: objectId
+          x-celigo-refModel: connectors
+          readOnly: true
+          description: |
+            Reference to the integration app that defines this resource.
+
+            This field is only populated for resources that are part of an integration app.
+            It contains the unique identifier (_id) of the integration app (connector)
+            that defines the structure, behavior, and templates for this resource.
+
+            The integration app is the published template that can be installed
+            multiple times across different accounts, with each installation creating
+            a separate integration instance (referenced by _integrationId).
+
+            This reference enables:
+            - Identifying the source integration app for this resource
+            - Determining which template version is being used
+            - Linking to documentation, support, and marketplace information
+          examples:
+            - 5e8d43a1b9e5a80011a35f1b
+          x-celigo-ai-guidance:
+            - |-
+              Read-only connector (Integration App template) reference; present only on
+              connector-owned resources. Never set or modify it when authoring resources.
+    AsyncHelper:
+      type: object
+      required:
+        - _id
+        - name
+        - http
+      description: Async helper object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/AsyncHelperBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - $ref: '#/components/schemas/IAResourceResponse'
+        - type: object
+          properties:
+            _templateId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: templates
+              description: Template this async helper was created from.
+              examples:
+                - 5c6c135fc802b3146e12eecf
+            _sourceId:
+              type: string
+              format: objectId
+              readOnly: true
+              description: Source resource this async helper was cloned from.
+              examples:
+                - 6256b8c0cddb8a1ba55198d5
+      x-celigo-ai-guidance:
+        - |-
+          An async helper bundles the polling configuration for an asynchronous
+          external API plus references to the status export (polled to check
+          progress) and the result export (fetches the final payload). It is
+          referenced from an export or import via `http._asyncHelperId`.
+    AsyncHelperRequest:
+      type: object
+      description: |
+        Request body for creating or replacing an async helper resource. All
+        required fields must be present for both POST (create) and PUT (replace)
+        operations.
+      required:
+        - name
+        - http
+      allOf:
+        - $ref: '#/components/schemas/AsyncHelperBase'
+      x-celigo-ai-guidance:
+        - |-
+          `name` and the status configuration (`http.status._exportId` and
+          `http.status.statusPath`) are the required fields. The status and result
+          exports referenced here must be ordinary exports that do not themselves
+          reference an async helper.
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    422-dependency-conflict:
+      description: |-
+        The resource has dependents that must be deleted first. Each entry
+        in the `errors` array names one blocking resource.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: dependencies_not_deleted
+                    message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+x-enable-proxy: true
+x-internal: false