@celigo/api-specs 0.2.196 → 0.2.197

package/dist/api.yml

@@ -2596,57 +2596,2862 @@ components:
           422 with its message. Any other `statusCode` is sent as returned.
     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'
+            - One structural blank: the single top-level `objectarray` item of a `rows [ ]` mapping (the
+              array output structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
+
+            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, an empty `generate` on a row inside an `arrayarray` row's
+            `buildArrayHelper` entry is that row's inner array (`arrayarray` fails at run time; see
+            `dataType`); other unnamed rows are the wrappers and source-only rows described above; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
+          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. Converts a numeric string (`"24"` → `24`,
+              `"007"` → `7`) and leaves the field out for an empty string; a value
+              holding letters or a thousands separator (`"1,250.00"`) fails the
+              record with `non_parsable_string` (`<generate>: String contains alpha
+              characters`)
+            - `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 from child mappings in the 'mappings' array, or
+              copies a whole object with `extract` (one or the other, not both)
+
+            **Array Types**
+            - `stringarray`: Array of strings
+            - `numberarray`: Array of numbers
+            - `booleanarray`: Array of booleans
+            - `objectarray`: Array of objects (most common array type)
+
+            `arrayarray` is not a type the mapper recognizes: a save accepts it, but every record
+            then fails with `Destination datatype is a required field.` Build an array of arrays
+            in a script hook instead.
+
+            Array dataTypes are populated two ways: construct or iterate through
+            `buildArrayHelper` entries, or set a constant with `hardCodedValue`. The
+            row's own `extract` is never read on an array type: a primitive-array row
+            that has only an `extract` (JSONPath, Handlebars or a literal) yields
+            nothing, with no error, and an `objectarray` row without `buildArrayHelper`
+            or `hardCodedValue` is refused with 422 ("buildArrayHelper" or
+            "hardCodedValue" must be present for object array datatype.). To copy a
+            source array through unchanged, use one entry that iterates it
+            (`buildArrayHelper: [{"extract": "$.items[*]"}]`).
+
+            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` or `hardCodedValue` (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.`
+            - |-
+              Give each row the type the destination field expects; `"string"` is
+              not a safe default. It accepts any source value, but sends a numeric
+              source as text (`"24"`), which a destination that checks JSON types
+              refuses. Map numeric destination fields as `number`, which fails a
+              record (`non_parsable_string`) only when the value holds letters or a
+              thousands separator.
+          enum:
+            - string
+            - number
+            - boolean
+            - object
+            - stringarray
+            - numberarray
+            - booleanarray
+            - objectarray
+          x-enumDescriptions:
+            string: Text values; converts other types to their string representation.
+            number: Numeric values; converts numeric strings, and fails the record (`non_parsable_string`) on letters or a thousands separator.
+            boolean: True/false values; converts truthy/falsy values.
+            object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
+            stringarray: Array of string values.
+            numberarray: Array of numeric values.
+            booleanarray: Array of boolean values.
+            objectarray: Array of objects, the most common array type.
+          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 '$' — the record root. An object record is addressed as
+              '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
+            - Used for precisely targeting data in structured JSON objects
+            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+              '$[*].Tax' (every row of a grouped record)
+            - Wildcards like [*] extract multiple values/objects
+            - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+              `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+              path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+              need no brackets (`$.Ship To Name`, `$.Tracking #`)
+            - Filter expressions such as `$.items[?(@.active)]` fail the record with
+              "Eval [?(expr)] prevented in JSONPath expression."
+
+            ```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; a grouped
+              (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
+            - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
+            - Valid on scalars and on `object` rows, where the rendered output must
+              parse into an object. On an array row the template goes in a
+              `buildArrayHelper` entry instead: on an `objectarray` row's own
+              `extract` it is refused with 422 ("buildArrayHelper" or "hardCodedValue"
+              must be present for object array datatype.), and on a primitive-array
+              row's own `extract` it yields nothing (the field is left out) without an
+              error
+
+            ```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
+            - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+              both: a row with both fails with 422 (`"extract" should not be present if
+              "mappings" field is present`). A `buildArrayHelper` entry is different: there
+              `extract` and `mappings` work together.
+            - The root is the record as it arrives: an object record roots at `$.field`; a
+              grouped record (an array of rows — grouped exports, file key columns, NetSuite
+              grouped saved searches) roots at the array, so its rows are addressed as
+              `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+              record's shape resolves to nothing without an error.
+
+            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:
+            - |-
+              ## GROUPED (ARRAY) RECORDS
+              Decide the JSONPath root from the record's shape before writing
+              any extract. When the record is an array of rows, `$.field`,
+              `$.properties.field` and `$.rows[*].field` all resolve to
+              nothing — the processor still reports success and the request
+              body ships as `{}`. Address rows as `$[0].field` (that row's
+              value, typed) or `$[*].field` (every row: joined with commas
+              into a `string` destination; rejected with
+              `incompatible_destination_conversion` into a `number`
+              destination). Column labels with spaces work as
+              `$[*][Order Number]`, `$[*].[Order Number]`, or
+              `$[*]['Order Number']`. For one destination element per row
+              the two array kinds take different helper forms: a primitive
+              array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+              [{"extract": "$[*].field"}]`; an `objectarray` uses
+              `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+              with the children addressing the row relatively (`$.field`,
+              `{{rows.field}}`). An `extract` placed directly on the
+              array-typed field yields nothing. Handlebars
+              extracts bind the array record as `rows` (`{{rows.0.field}}`),
+              an object record as `record`. The reverse holds too: `$[*]` on
+              an object record iterates the object's values, not rows.
+            - |-
+              ## 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 missing or an empty string (the UI's "Do nothing" action),
+            while a null source is still written as null unless `conditional.when` is
+            `extract_not_empty`. Failing the record instead is `conditional.when:
+            fail_record_when_empty`, which excludes a default.
+          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" (a missing or `""` source is left out
+              of the output, while a null source is written as null unless
+              `conditional.when` is `extract_not_empty`).
+            - |-
+              The four "Action to take if source field has no value" choices map to:
+              do nothing → no `default` key (add `conditional.when:
+              extract_not_empty` to leave a null source out too; without it a null
+              source is written as null); use null → `"default": null`; use empty string or
+              a custom value → `"default": "<value>"`; cause the record to fail →
+              `conditional.when: fail_record_when_empty` with no `default` key.
+          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.
+            On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+            is dropped on save. On an import, a name that matches no lookup fails every record
+            with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+            doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+            the field left out, lets the record succeed with the lookup's `default`, or without
+            the mapped field when there is none.
+
+            ```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
+        hardCodedValue:
+          type:
+            - string
+            - 'null'
+          description: |
+            Constant written to the destination instead of an extracted value. On a primitive
+            array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
+            verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
+            On an `object` it must be a JSON object string and on an `objectarray` a JSON array
+            string (an object string becomes one element); the save parses it and refuses non-JSON
+            or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+            JSON `null` writes the destination field as null; it is what the mapper saves for its
+            hard-coded "Use null as default value" choice.
+          examples:
+            - USD
+            - A,B
+            - '[{"code": "A"}, {"code": "B"}]'
+        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)
+
+            **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. On a grouped (array)
+              record the record itself is the array to iterate: `"$[*]"`
+              yields one `objectarray` element per row (children address the
+              row as `$.field`), and `"$[*].field"` yields one primitive-array
+              value per row. 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.
+            - |-
+              An entry's `extract` can be a Handlebars template. On an
+              `objectarray` it must render a JSON object (one element) or a JSON
+              array (one element per item). On a primitive array each entry
+              renders one element, so a serialized array becomes one string
+              element. A bare literal entry extract is refused with 422 ("extract
+              only supports json path or handlebars expression"); set a constant
+              with the row's `hardCodedValue` instead.
+          description: |
+            **Purpose**
+            Configures how to construct arrays in the output record, handling various array types and inputs.
+
+            **Guidance**
+            This is the mechanism for building array data types:
+
+            **When to Use**
+            - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
+              row sets `hardCodedValue`: an array row's own `extract` is never read (see `dataType`)
+            - 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;
+              on a grouped (array) record the record itself is the array, so the
+              path roots at it ($[*].name — one value per row)
+            - 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
+                  ]
+                }
+              ]
+            }
+            ```
+
+            **Arrays of Arrays**
+            - The mapper has no working type for them: `arrayarray` saves, but every record
+              fails with `Destination datatype is a required field.` Build an array of arrays
+              in a script hook instead.
+
+            **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 be a JSON path that iterates an array:
+              '$.items[*]' when the array is a field of an object record, or '$[*]'
+              (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+              grouped array of rows. A CONSTRUCTED entry (child mappings building one
+              element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+              into an 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.
+
+                  An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                  element per item, with no error. Child extracts drop the `[*]` but keep the
+                  array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                  element-relative `$.sku` reads the record root instead of the element.
+                examples:
+                  - $.items[*]
+                  - $.order.lineItems[*]
+                  - $.parents[*].children[*]
+                  - $
+              name:
+                type: string
+                maxLength: 200
+                description: |
+                  Display label for this source object in the mapper, so the sources of
+                  an object array can be told apart instead of all showing as `$`.
+                  Has no effect at runtime; stored only when non-empty.
+                x-celigo-ai-guidance:
+                  - |-
+                    Carry an existing `name` through every edit — it is the user's label
+                    for the tab, and an entry sent without it loses the label. Duplicate
+                    names across entries are allowed. Set one only when the user names
+                    the source object; never invent labels.
+                examples:
+                  - Billing address
+                  - Shipping address
+              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.
+                x-celigo-ai-guidance:
+                  - |-
+                    Judged against this entry's own `extract` (the array source). The
+                    design scopes the UI's tab-level "Action to take if source field has
+                    no value" to copy-as-is tabs (no child `mappings`); the API accepts
+                    `fail_record_when_empty` on a mapped entry as well, and the mapper
+                    processor honors it there — the record fails when that array is
+                    missing or empty (`errors[]` entry `code: extract_empty`, `fatal:
+                    true`, message `<generate>: Source field has no value`; probed
+                    2026-10-09). Say so when writing it on a mapped entry: the user may
+                    not find the setting in the mapper's tab. To fail on an empty field
+                    inside each element, set the action on that child mapping instead.
+                properties:
+                  when:
+                    type: string
+                    description: |
+                      Condition judged on the entry's extract — skip the elements the
+                      extract does not return, or fail the whole record when the source
+                      array is missing or empty.
+                    enum:
+                      - extract_not_empty
+                      - fail_record_when_empty
+                    x-enumDescriptions:
+                      extract_not_empty: Include an array element only when the extract returns a non-empty value for it
+                      fail_record_when_empty: Fail the record when the entry's source array is missing or empty
+                    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
+            if:
+              properties:
+                conditional:
+                  properties:
+                    when:
+                      const: fail_record_when_empty
+                  required:
+                    - when
+              required:
+                - conditional
+            then:
+              not:
+                required:
+                  - default
+        status:
+          type: string
+          description: |
+            **Purpose**
+            Controls whether the mapping is applied. Send it on every mapping entry.
+
+            **Guidance**
+            Only `Active` rows run. `Draft` and `Inactive` rows keep their
+            configuration, are saved with minimal validation, and are skipped at
+            runtime and in preview; a non-Active parent skips its whole subtree
+            whatever its children say. Imports (on save and in the mapper processor)
+            and API response mappings reject a row missing this field (validation
+            error: "Mapping object must have status field present."); a Tool's
+            output mapping saves and runs one, which is why `required` doesn't
+            list it.
+          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.`
+            - |-
+              `"Inactive"` is the user's "Set inactive" on a row: use it only when
+              asked to disable or park a row, never to mean incomplete (that is
+              `"Draft"`). Setting a parent `Inactive` means no `Active` row may
+              remain under it — the save rejects an `Active` row under an
+              `Inactive` parent (`[inactive_parent_active_child]` on `mappings`,
+              no message text) and never cascades or promotes on its own; `Draft`
+              descendants are kept as they are, and a `Draft` parent does not gate
+              its children. The UI's Set inactive on a parent marks the parent and
+              every child `Inactive`. Re-enabling a child
+              means re-enabling its ancestors in the same payload. Edits that keep
+              existing rows must carry their stored status forward — rewriting a
+              `Draft` or `Inactive` row to `Active` turns a row the user parked
+              back on.
+          enum:
+            - Active
+            - Draft
+            - Inactive
+          x-enumDescriptions:
+            Active: The mapping is enabled and applied during processing
+            Draft: In-progress mapping; saved without the Active-only field validations and skipped at runtime
+            Inactive: Disabled by the user; configuration kept, skipped at runtime and in preview
+          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
+
+            - `fail_record_when_empty`: Fail the record when the extract field returns
+              no value (the UI's "Cause record to fail" action when the source field
+              has no value)
+
+            **Example**
+            ```json
+            {
+              "generate": "statusMessage",
+              "dataType": "string",
+              "status": "Active",
+              "extract": "$.status.message",
+              "conditional": {
+                "when": "extract_not_empty"  // Only map when status.message exists
+              }
+            }
+            ```
+          x-celigo-ai-guidance:
+            - |-
+              `when` holds one value, and two different settings share it: the
+              composite-import operation gate (`record_created` / `record_updated`,
+              the UI's "Only perform mapping when") and the empty-source action
+              (`extract_not_empty` / `fail_record_when_empty`, the UI's "Action to
+              take if source field has no value"). A row cannot carry both — writing
+              one replaces the other and the save succeeds, so a composite import
+              row that needs both has to choose. Never author `fail_record_when_empty`
+              on a row that already carries `record_created` or `record_updated`.
+          properties:
+            when:
+              type: string
+              description: |
+                Condition that gates this mapping — either an operation gate on a
+                composite (create-or-update) import or the action to take when the
+                extract returns no value. Empty means null, undefined or an empty
+                string; `0`, `false` and whitespace are values.
+              x-celigo-ai-guidance:
+                - |-
+                  `fail_record_when_empty` is the fourth "Action to take if source field
+                  has no value" and is mutually exclusive with the other three: send it
+                  with no `default` key. A `default`, a `lookupName` or a `hardCodedValue`
+                  on the same row — or a `default` on a `buildArrayHelper` entry — is
+                  rejected at save with `[unsupported_mapping] "<key>" and conditional.when
+                  "fail_record_when_empty" cannot be present in mapping simultaneously.`
+                  (the lookup variant adds `Use lookup "allowFailures" instead.`);
+                  lookups fail through `allowFailures: false`, and a hard-coded row
+                  always has a value. At runtime an empty extract fails the record with
+                  an `errors[]` entry `{code: "extract_empty", fatal: true, source:
+                  "mapping", message: "<generate>: Source field has no value"}`
+                  ("Input field has no value" in a Transformation 2.0); `0` and `false`
+                  are values and map through.
+              enum:
+                - record_created
+                - record_updated
+                - extract_not_empty
+                - fail_record_when_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
+                fail_record_when_empty: Fail the record when the extract field returns no value
+              examples:
+                - record_created
+                - record_updated
+                - extract_not_empty
+                - fail_record_when_empty
       required:
         - dataType
+      if:
+        properties:
+          conditional:
+            properties:
+              when:
+                const: fail_record_when_empty
+            required:
+              - when
+        required:
+          - conditional
+      then:
+        not:
+          anyOf:
+            - required:
+                - default
+            - required:
+                - lookupName
+            - required:
+                - hardCodedValue
+    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 and arrays of objects, to any depth) are ALL
+           handled through this recursive pattern; an array of arrays is not (build one in a script hook)
+        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.
+
+        On save, a leaf row with neither a source (`extract`, `hardCodedValue`, `lookupName`) nor a
+        destination (`generate`) is dropped silently, at every nesting level, and so is an object or
+        object-array row left with no source, no destination and no remaining child `mappings` or
+        `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
+        wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
+      x-celigo-ai-guidance:
+        - |-
+          Rows that exist in the saved document — including `Draft` and `Inactive` rows and
+          rows with only a source or only a destination — are the user's state: an edit that
+          re-sends the tree must carry them through unchanged unless the user asked to change
+          them. Only a row with neither source nor destination — and, for an object or
+          object-array row, no remaining children — can be left out; the save would drop it
+          anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
+      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'
+              - One structural blank: the single top-level `objectarray` item of a `rows [ ]` mapping (the
+                array output structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
+
+              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, an empty `generate` on a row inside an `arrayarray` row's
+              `buildArrayHelper` entry is that row's inner array (`arrayarray` fails at run time; see
+              `dataType`); other unnamed rows are the wrappers and source-only rows described above; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
+            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. Converts a numeric string (`"24"` → `24`,
+                `"007"` → `7`) and leaves the field out for an empty string; a value
+                holding letters or a thousands separator (`"1,250.00"`) fails the
+                record with `non_parsable_string` (`<generate>: String contains alpha
+                characters`)
+              - `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 from child mappings in the 'mappings' array, or
+                copies a whole object with `extract` (one or the other, not both)
+
+              **Array Types**
+              - `stringarray`: Array of strings
+              - `numberarray`: Array of numbers
+              - `booleanarray`: Array of booleans
+              - `objectarray`: Array of objects (most common array type)
+
+              `arrayarray` is not a type the mapper recognizes: a save accepts it, but every record
+              then fails with `Destination datatype is a required field.` Build an array of arrays
+              in a script hook instead.
+
+              Array dataTypes are populated two ways: construct or iterate through
+              `buildArrayHelper` entries, or set a constant with `hardCodedValue`. The
+              row's own `extract` is never read on an array type: a primitive-array row
+              that has only an `extract` (JSONPath, Handlebars or a literal) yields
+              nothing, with no error, and an `objectarray` row without `buildArrayHelper`
+              or `hardCodedValue` is refused with 422 ("buildArrayHelper" or
+              "hardCodedValue" must be present for object array datatype.). To copy a
+              source array through unchanged, use one entry that iterates it
+              (`buildArrayHelper: [{"extract": "$.items[*]"}]`).
+
+              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` or `hardCodedValue` (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.`
+              - |-
+                Give each row the type the destination field expects; `"string"` is
+                not a safe default. It accepts any source value, but sends a numeric
+                source as text (`"24"`), which a destination that checks JSON types
+                refuses. Map numeric destination fields as `number`, which fails a
+                record (`non_parsable_string`) only when the value holds letters or a
+                thousands separator.
+            enum:
+              - string
+              - number
+              - boolean
+              - object
+              - stringarray
+              - numberarray
+              - booleanarray
+              - objectarray
+            x-enumDescriptions:
+              string: Text values; converts other types to their string representation.
+              number: Numeric values; converts numeric strings, and fails the record (`non_parsable_string`) on letters or a thousands separator.
+              boolean: True/false values; converts truthy/falsy values.
+              object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
+              stringarray: Array of string values.
+              numberarray: Array of numeric values.
+              booleanarray: Array of boolean values.
+              objectarray: Array of objects, the most common array type.
+            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 '$' — the record root. An object record is addressed as
+                '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
+              - Used for precisely targeting data in structured JSON objects
+              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+                '$[*].Tax' (every row of a grouped record)
+              - Wildcards like [*] extract multiple values/objects
+              - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+                `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+                path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+                need no brackets (`$.Ship To Name`, `$.Tracking #`)
+              - Filter expressions such as `$.items[?(@.active)]` fail the record with
+                "Eval [?(expr)] prevented in JSONPath expression."
+
+              ```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; a grouped
+                (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
+              - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
+              - Valid on scalars and on `object` rows, where the rendered output must
+                parse into an object. On an array row the template goes in a
+                `buildArrayHelper` entry instead: on an `objectarray` row's own
+                `extract` it is refused with 422 ("buildArrayHelper" or "hardCodedValue"
+                must be present for object array datatype.), and on a primitive-array
+                row's own `extract` it yields nothing (the field is left out) without an
+                error
+
+              ```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
+              - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+                both: a row with both fails with 422 (`"extract" should not be present if
+                "mappings" field is present`). A `buildArrayHelper` entry is different: there
+                `extract` and `mappings` work together.
+              - The root is the record as it arrives: an object record roots at `$.field`; a
+                grouped record (an array of rows — grouped exports, file key columns, NetSuite
+                grouped saved searches) roots at the array, so its rows are addressed as
+                `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+                record's shape resolves to nothing without an error.
+
+              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:
+              - |-
+                ## GROUPED (ARRAY) RECORDS
+                Decide the JSONPath root from the record's shape before writing
+                any extract. When the record is an array of rows, `$.field`,
+                `$.properties.field` and `$.rows[*].field` all resolve to
+                nothing — the processor still reports success and the request
+                body ships as `{}`. Address rows as `$[0].field` (that row's
+                value, typed) or `$[*].field` (every row: joined with commas
+                into a `string` destination; rejected with
+                `incompatible_destination_conversion` into a `number`
+                destination). Column labels with spaces work as
+                `$[*][Order Number]`, `$[*].[Order Number]`, or
+                `$[*]['Order Number']`. For one destination element per row
+                the two array kinds take different helper forms: a primitive
+                array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+                [{"extract": "$[*].field"}]`; an `objectarray` uses
+                `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+                with the children addressing the row relatively (`$.field`,
+                `{{rows.field}}`). An `extract` placed directly on the
+                array-typed field yields nothing. Handlebars
+                extracts bind the array record as `rows` (`{{rows.0.field}}`),
+                an object record as `record`. The reverse holds too: `$[*]` on
+                an object record iterates the object's values, not rows.
+              - |-
+                ## 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 missing or an empty string (the UI's "Do nothing" action),
+              while a null source is still written as null unless `conditional.when` is
+              `extract_not_empty`. Failing the record instead is `conditional.when:
+              fail_record_when_empty`, which excludes a default.
+            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" (a missing or `""` source is left out
+                of the output, while a null source is written as null unless
+                `conditional.when` is `extract_not_empty`).
+              - |-
+                The four "Action to take if source field has no value" choices map to:
+                do nothing → no `default` key (add `conditional.when:
+                extract_not_empty` to leave a null source out too; without it a null
+                source is written as null); use null → `"default": null`; use empty string or
+                a custom value → `"default": "<value>"`; cause the record to fail →
+                `conditional.when: fail_record_when_empty` with no `default` key.
+            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.
+              On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+              is dropped on save. On an import, a name that matches no lookup fails every record
+              with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+              doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+              the field left out, lets the record succeed with the lookup's `default`, or without
+              the mapped field when there is none.
+
+              ```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
+          hardCodedValue:
+            type:
+              - string
+              - 'null'
+            description: |
+              Constant written to the destination instead of an extracted value. On a primitive
+              array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
+              verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
+              On an `object` it must be a JSON object string and on an `objectarray` a JSON array
+              string (an object string becomes one element); the save parses it and refuses non-JSON
+              or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+              JSON `null` writes the destination field as null; it is what the mapper saves for its
+              hard-coded "Use null as default value" choice.
+            examples:
+              - USD
+              - A,B
+              - '[{"code": "A"}, {"code": "B"}]'
+          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)
+
+              **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. On a grouped (array)
+                record the record itself is the array to iterate: `"$[*]"`
+                yields one `objectarray` element per row (children address the
+                row as `$.field`), and `"$[*].field"` yields one primitive-array
+                value per row. 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.
+              - |-
+                An entry's `extract` can be a Handlebars template. On an
+                `objectarray` it must render a JSON object (one element) or a JSON
+                array (one element per item). On a primitive array each entry
+                renders one element, so a serialized array becomes one string
+                element. A bare literal entry extract is refused with 422 ("extract
+                only supports json path or handlebars expression"); set a constant
+                with the row's `hardCodedValue` instead.
+            description: |
+              **Purpose**
+              Configures how to construct arrays in the output record, handling various array types and inputs.
+
+              **Guidance**
+              This is the mechanism for building array data types:
+
+              **When to Use**
+              - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
+                row sets `hardCodedValue`: an array row's own `extract` is never read (see `dataType`)
+              - 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;
+                on a grouped (array) record the record itself is the array, so the
+                path roots at it ($[*].name — one value per row)
+              - 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
+                    ]
+                  }
+                ]
+              }
+              ```
+
+              **Arrays of Arrays**
+              - The mapper has no working type for them: `arrayarray` saves, but every record
+                fails with `Destination datatype is a required field.` Build an array of arrays
+                in a script hook instead.
+
+              **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 be a JSON path that iterates an array:
+                '$.items[*]' when the array is a field of an object record, or '$[*]'
+                (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+                grouped array of rows. A CONSTRUCTED entry (child mappings building one
+                element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+                into an 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.
+
+                    An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                    element per item, with no error. Child extracts drop the `[*]` but keep the
+                    array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                    element-relative `$.sku` reads the record root instead of the element.
+                  examples:
+                    - $.items[*]
+                    - $.order.lineItems[*]
+                    - $.parents[*].children[*]
+                    - $
+                name:
+                  type: string
+                  maxLength: 200
+                  description: |
+                    Display label for this source object in the mapper, so the sources of
+                    an object array can be told apart instead of all showing as `$`.
+                    Has no effect at runtime; stored only when non-empty.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Carry an existing `name` through every edit — it is the user's label
+                      for the tab, and an entry sent without it loses the label. Duplicate
+                      names across entries are allowed. Set one only when the user names
+                      the source object; never invent labels.
+                  examples:
+                    - Billing address
+                    - Shipping address
+                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.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Judged against this entry's own `extract` (the array source). The
+                      design scopes the UI's tab-level "Action to take if source field has
+                      no value" to copy-as-is tabs (no child `mappings`); the API accepts
+                      `fail_record_when_empty` on a mapped entry as well, and the mapper
+                      processor honors it there — the record fails when that array is
+                      missing or empty (`errors[]` entry `code: extract_empty`, `fatal:
+                      true`, message `<generate>: Source field has no value`; probed
+                      2026-10-09). Say so when writing it on a mapped entry: the user may
+                      not find the setting in the mapper's tab. To fail on an empty field
+                      inside each element, set the action on that child mapping instead.
+                  properties:
+                    when:
+                      type: string
+                      description: |
+                        Condition judged on the entry's extract — skip the elements the
+                        extract does not return, or fail the whole record when the source
+                        array is missing or empty.
+                      enum:
+                        - extract_not_empty
+                        - fail_record_when_empty
+                      x-enumDescriptions:
+                        extract_not_empty: Include an array element only when the extract returns a non-empty value for it
+                        fail_record_when_empty: Fail the record when the entry's source array is missing or empty
+                      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
+              if:
+                properties:
+                  conditional:
+                    properties:
+                      when:
+                        const: fail_record_when_empty
+                    required:
+                      - when
+                required:
+                  - conditional
+              then:
+                not:
+                  required:
+                    - default
+          status:
+            type: string
+            description: |
+              **Purpose**
+              Controls whether the mapping is applied. Send it on every mapping entry.
+
+              **Guidance**
+              Only `Active` rows run. `Draft` and `Inactive` rows keep their
+              configuration, are saved with minimal validation, and are skipped at
+              runtime and in preview; a non-Active parent skips its whole subtree
+              whatever its children say. Imports (on save and in the mapper processor)
+              and API response mappings reject a row missing this field (validation
+              error: "Mapping object must have status field present."); a Tool's
+              output mapping saves and runs one, which is why `required` doesn't
+              list it.
+            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.`
+              - |-
+                `"Inactive"` is the user's "Set inactive" on a row: use it only when
+                asked to disable or park a row, never to mean incomplete (that is
+                `"Draft"`). Setting a parent `Inactive` means no `Active` row may
+                remain under it — the save rejects an `Active` row under an
+                `Inactive` parent (`[inactive_parent_active_child]` on `mappings`,
+                no message text) and never cascades or promotes on its own; `Draft`
+                descendants are kept as they are, and a `Draft` parent does not gate
+                its children. The UI's Set inactive on a parent marks the parent and
+                every child `Inactive`. Re-enabling a child
+                means re-enabling its ancestors in the same payload. Edits that keep
+                existing rows must carry their stored status forward — rewriting a
+                `Draft` or `Inactive` row to `Active` turns a row the user parked
+                back on.
+            enum:
+              - Active
+              - Draft
+              - Inactive
+            x-enumDescriptions:
+              Active: The mapping is enabled and applied during processing
+              Draft: In-progress mapping; saved without the Active-only field validations and skipped at runtime
+              Inactive: Disabled by the user; configuration kept, skipped at runtime and in preview
+            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
+
+              - `fail_record_when_empty`: Fail the record when the extract field returns
+                no value (the UI's "Cause record to fail" action when the source field
+                has no value)
+
+              **Example**
+              ```json
+              {
+                "generate": "statusMessage",
+                "dataType": "string",
+                "status": "Active",
+                "extract": "$.status.message",
+                "conditional": {
+                  "when": "extract_not_empty"  // Only map when status.message exists
+                }
+              }
+              ```
+            x-celigo-ai-guidance:
+              - |-
+                `when` holds one value, and two different settings share it: the
+                composite-import operation gate (`record_created` / `record_updated`,
+                the UI's "Only perform mapping when") and the empty-source action
+                (`extract_not_empty` / `fail_record_when_empty`, the UI's "Action to
+                take if source field has no value"). A row cannot carry both — writing
+                one replaces the other and the save succeeds, so a composite import
+                row that needs both has to choose. Never author `fail_record_when_empty`
+                on a row that already carries `record_created` or `record_updated`.
+            properties:
+              when:
+                type: string
+                description: |
+                  Condition that gates this mapping — either an operation gate on a
+                  composite (create-or-update) import or the action to take when the
+                  extract returns no value. Empty means null, undefined or an empty
+                  string; `0`, `false` and whitespace are values.
+                x-celigo-ai-guidance:
+                  - |-
+                    `fail_record_when_empty` is the fourth "Action to take if source field
+                    has no value" and is mutually exclusive with the other three: send it
+                    with no `default` key. A `default`, a `lookupName` or a `hardCodedValue`
+                    on the same row — or a `default` on a `buildArrayHelper` entry — is
+                    rejected at save with `[unsupported_mapping] "<key>" and conditional.when
+                    "fail_record_when_empty" cannot be present in mapping simultaneously.`
+                    (the lookup variant adds `Use lookup "allowFailures" instead.`);
+                    lookups fail through `allowFailures: false`, and a hard-coded row
+                    always has a value. At runtime an empty extract fails the record with
+                    an `errors[]` entry `{code: "extract_empty", fatal: true, source:
+                    "mapping", message: "<generate>: Source field has no value"}`
+                    ("Input field has no value" in a Transformation 2.0); `0` and `false`
+                    are values and map through.
+                enum:
+                  - record_created
+                  - record_updated
+                  - extract_not_empty
+                  - fail_record_when_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
+                  fail_record_when_empty: Fail the record when the extract field returns no value
+                examples:
+                  - record_created
+                  - record_updated
+                  - extract_not_empty
+                  - fail_record_when_empty
+        required:
+          - dataType
+        if:
+          properties:
+            conditional:
+              properties:
+                when:
+                  const: fail_record_when_empty
+              required:
+                - when
+          required:
+            - conditional
+        then:
+          not:
+            anyOf:
+              - required:
+                  - default
+              - required:
+                  - lookupName
+              - required:
+                  - hardCodedValue
+    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 true or omitted
+
+              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"
+
+              A save refuses a default together with an explicit `allowFailures: false`
+              (422 `Lookups with default set can not have allowFailures explicitly set to
+              false.`): a lookup either fails a miss (`allowFailures: false`, no default) or
+              falls back to its default.
+            examples:
+              - Unknown
+              - Other
+              - N/A
+              - Unmapped Value
+              - '{Original Value}'
+            x-celigo-ai-guidance:
+              - 'Omit this field entirely when no fallback value is intended: a miss the lookup lets through then leaves the mapped field out, and `allowFailures: false` (which a save refuses alongside a default) fails it. An empty string is a value, not "no default" — the save accepts `default: ""`, and an allowed miss writes `""`.'
+              - A default sends every unmapped value with no error, so add the missing key to the map when the destination needs the real value; keys match the extracted value exactly (case, spacing and suffixes count), and a save replaces the whole map.
+          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 (`lookup_error` for a
+                static map, `lookupcache_evaluation_failed` for a lookup cache)
+              - omitted or null: the record doesn't fail either. On an import a static lookup writes
+                its default if it has one, and a static or cache lookup without one leaves the
+                mapped field out of the output, with no error
+
+              **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
+
+              A default raises no error: records that miss go out with the default value and
+              nothing reports them. Use true only when that fallback is acceptable at the
+              destination, and set false explicitly when a missing value must stop the record.
+            examples:
+              - true
+              - false
+            x-celigo-ai-guidance:
+              - 'Never leave this field out to mean "fail on a miss": on an import, an omitted or null value lets a missing key through without an error (with the default, or without the mapped field when there is none). Only an explicit false fails the record.'
+    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:
-        generate:
-          type: string
-          description: Record field the row writes.
-          examples:
-            - customerId
-        extract:
-          type: string
-          description: JSONPath into the request body that the value is read from.
-          examples:
-            - $.id
-        dataType:
+        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:
-            - string
-            - number
-            - boolean
-            - object
-            - stringarray
-            - numberarray
-            - booleanarray
-            - objectarray
+            - expression
+            - script
           x-enumDescriptions:
-            string: Single string value
-            number: Single numeric value
-            boolean: Single boolean value
-            object: Nested object value
-            stringarray: Array of strings
-            numberarray: Array of numbers
-            booleanarray: Array of booleans
-            objectarray: Array of objects
-          description: Data type the row writes.
-          examples:
-            - string
-        sourceDataType:
-          type: string
-          description: Data type of the extracted value.
-          examples:
-            - string
-        status:
-          type: string
-          description: Row status; `Active` rows run.
+            expression: Rule-based transformation using declarative mapping definitions.
+            script: Script-based transformation using custom JavaScript logic.
           examples:
-            - Active
-        mappings:
-          type: array
-          description: Child rows of an `object` row, with the same shape as this row.
-          items:
-            $ref: '#/components/schemas/items'
+            - 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.
+                - |-
+                  An import's ``responseTransform`` is the exception: it accepts
+                  version ``"1"`` only (``"2"`` is refused with 422, verified live
+                  2026-10-21), so there, map every response field that response
+                  mapping needs.
+              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.
+                  x-celigo-ai-guidance:
+                    - |-
+                      On a grouped record (the export groups rows, so the record is an
+                      array) only `create` can author output — build it from the rows with
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `modify` has no object to overlay onto an array: the record passes
+                      through untouched and the processor reports success. Either mode
+                      reshapes the inside of one record; neither changes how many records
+                      the page carries (that is the export's `preSavePage` hook) or whether
+                      the export groups at all (that is its grouping setting).
+                  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, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                  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: {...}, job, testMode, settings, headers,
+                        queryParams}` (plus `fileMeta` on file-provider steps).
+                        `mappings[].extract` JSONPath MUST include the
+                        `record.` segment for record fields — e.g.
+                        `"$.record.orderId"` — and reads `headers` and
+                        `queryParams` beside it (`$.headers['X-Id']`);
+                        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.
+                    - |-
+                      In `envelope` mode the output is still a bare record: a
+                      `modify` transform returns the record with its mapped
+                      fields merged in (no `record` wrapper, no `job` or
+                      `settings` keys), and a `create` transform returns only
+                      the mapped fields.
+                    - |-
+                      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: {...}, job, testMode, settings, headers,
+                        queryParams}`` (plus ``fileMeta`` on file-provider
+                        steps; ``headers`` and ``queryParams`` sit beside
+                        ``record``) — the
+                        same runtime-context envelope Handlebars / SQL /
+                        GraphQL templates render against.  ``mappings[].extract``
+                        JSONPath values for record fields MUST include the
+                        ``record.`` segment — for example ``"$.record.orderId"``
+                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        ``queryParams`` are read beside it
+                        (``"$.headers['X-Id']"``).  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.  Read this value before
+                      writing ``mappings[].extract`` 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. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
+              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
     ApiRequest:
       type: object
       description: Request configuration for a builder-mode API endpoint.
@@ -2843,114 +5648,35 @@ components:
               its mockResponse or a placeholder). Can include body, headers, pathParams, and
               queryParams; only the body reaches the record the steps see.
         transform:
-          type: object
           description: |-
-            Optional transformation applied to the incoming request before processing. The
-            expression form (`type: "expression"` with Transformation 2.0 rules in `expression`)
-            saves and runs. In a test run its rules see only the request body, not `pathParams`,
-            `queryParams` or headers.
-          properties:
-            type:
-              type: string
-              description: Selects the transform form; `expression` runs the rules in `expression`.
-              examples:
-                - expression
-            expression:
-              type: object
-              description: Transformation 2.0 rules applied to the request body.
-              properties:
-                version:
-                  type: string
-                  description: Rule format; `"2"` selects the rules in `rulesTwoDotZero`.
-                  examples:
-                    - '2'
-                rulesTwoDotZero:
-                  type: object
-                  description: The rules applied to the request body.
-                  properties:
-                    mode:
-                      type: string
-                      enum:
-                        - create
-                        - modify
-                      x-enumDescriptions:
-                        create: Builds a new record from the mappings, dropping unmapped fields.
-                        modify: Edits the incoming record, keeping unmapped fields.
-                      description: How the mappings apply to the record; `modify` keeps the body's own fields beside the mapped ones.
-                      examples:
-                        - modify
-                    mappings:
-                      type: array
-                      description: Mapper 2.0 rows that write fields onto the record.
-                      items:
-                        type: object
-                        required:
-                          - dataType
-                        properties:
-                          generate:
-                            type: string
-                            description: Record field the row writes.
-                            examples:
-                              - customerId
-                          extract:
-                            type: string
-                            description: JSONPath into the request body that the value is read from.
-                            examples:
-                              - $.id
-                          dataType:
-                            type: string
-                            enum:
-                              - string
-                              - number
-                              - boolean
-                              - object
-                              - stringarray
-                              - numberarray
-                              - booleanarray
-                              - objectarray
-                            x-enumDescriptions:
-                              string: Single string value
-                              number: Single numeric value
-                              boolean: Single boolean value
-                              object: Nested object value
-                              stringarray: Array of strings
-                              numberarray: Array of numbers
-                              booleanarray: Array of booleans
-                              objectarray: Array of objects
-                            description: Data type the row writes.
-                            examples:
-                              - string
-                          sourceDataType:
-                            type: string
-                            description: Data type of the extracted value.
-                            examples:
-                              - string
-                          status:
-                            type: string
-                            description: Row status; `Active` rows run.
-                            examples:
-                              - Active
-                          mappings:
-                            type: array
-                            description: Child rows of an `object` row, with the same shape as this row.
-                            items:
-                              $ref: '#/components/schemas/items'
-            _scriptId:
-              type: string
-              format: objectId
-              x-celigo-refModel: scripts
-              description: Reference to a script for custom transformation logic.
-              examples:
-                - 689212a2c42d988978e27a11
-            function:
-              type: string
-              description: Function name in the script to execute.
-              examples:
-                - transformRequest
+            Optional transformation applied to the incoming request before processing. It takes the
+            same forms as an export's `transform`: Transformation 2.0 rules, legacy version 1 `rules`,
+            or a `script`. In a test run the body is the only part of the request the rules see (under
+            `record` when `inputContext` is `envelope`); `pathParams`, `queryParams` and headers are
+            not passed to them.
+          allOf:
+            - $ref: '#/components/schemas/Transform'
           x-celigo-ai-guidance:
             - |-
               Transforms the request data before it is processed by routers or responses.
               Useful for normalizing data or extracting specific fields.
+            - |-
+              Put a script's id and function under `script` (`script._scriptId`, `script.function`).
+              Sent at the top level of `transform` they are dropped without an error, and the API is
+              saved with no transform at all.
+            - |-
+              In an API test run, an `envelope` input context holds only `job`, `lookupCacheOptions`,
+              `record` (the request body), `settings` and `testMode`: no `pathParams`, and none of the
+              `headers`, `queryParams` or `fileMeta` keys listed on `inputContext`. There
+              `$.record.<field>` and `{{record.<field>}}` resolve while `$.pathParams`, `$.queryParams`
+              and `$.headers` resolve to nothing even when the run's `mockRequest` carries them, so a
+              test run cannot show whether rules that read request params or headers work; a real
+              call's envelope was not probed.
+            - |-
+              On an API request transform, a `script._scriptId` that names no script fails the save
+              with 422 `invalid_ref` and the message
+              "<id> is not a valid builder.request.transform.script._scriptId", not the message
+              quoted on `script._scriptId`. A script from another account was not probed on this path.
       required:
         - relativeURI
         - method
@@ -3460,10 +6186,14 @@ components:
           items:
             $ref: '#/components/schemas/items-2'
         hardCodedValue:
-          type: string
+          type:
+            - string
+            - 'null'
           description: |-
             Static value written to the target field instead of extracting
-            from input data.
+            from input data. JSON `null` writes the destination field as null;
+            it is what the mapper saves for its hard-coded
+            "Use null as default value" choice.
           x-celigo-ai-guidance:
             - |-
               The field name is exactly `hardCodedValue` (capital C). The
@@ -3775,10 +6505,14 @@ components:
                 items:
                   $ref: '#/components/schemas/items-2'
               hardCodedValue:
-                type: string
+                type:
+                  - string
+                  - 'null'
                 description: |-
                   Static value written to the target field instead of extracting
-                  from input data.
+                  from input data. JSON `null` writes the destination field as null;
+                  it is what the mapper saves for its hard-coded
+                  "Use null as default value" choice.
                 x-celigo-ai-guidance:
                   - |-
                     The field name is exactly `hardCodedValue` (capital C). The