@celigo/api-specs 0.2.154 → 0.2.156

package/dist/ai-agent.yml

@@ -2296,9 +2296,8 @@ components:
             - 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'
-            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
-              and 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
+            - 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
 
@@ -2315,7 +2314,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            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:
@@ -2349,17 +2350,25 @@ components:
             - `numberarray`: Array of numbers
             - `booleanarray`: Array of booleans
             - `objectarray`: Array of objects (most common array type)
-            - `arrayarray`: Array of arrays (for matrix/table structures)
 
-            Array dataTypes can be populated three ways: pass a source array
-            through unchanged via a JSONPath `extract` alone (when the source is
-            already an array of the right shape), construct/iterate via
-            `buildArrayHelper`, or set a constant with `hardCodedValue`.
+            `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: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
+            - 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.
@@ -2378,7 +2387,6 @@ components:
             - numberarray
             - booleanarray
             - objectarray
-            - arrayarray
           x-enumDescriptions:
             string: Text values; converts other types to their string representation.
             number: Numeric values; attempts conversion from strings.
@@ -2388,7 +2396,6 @@ components:
             numberarray: Array of numeric values.
             booleanarray: Array of boolean values.
             objectarray: Array of objects, the most common array type.
-            arrayarray: Array of arrays, used for matrix or table structures.
           examples:
             - string
             - number
@@ -2431,9 +2438,10 @@ components:
             - 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" must be present
-              for object array datatype), and on a primitive-array row's own
-              `extract` it renders null without an error
+              `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
@@ -2575,8 +2583,10 @@ components:
             Explicit JSON `null` is itself a valid fallback: the destination field is written as
             JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
             action). Omitting the key entirely means no fallback — the field is left out of the
-            output when the extract is empty (the UI's "Do nothing" action). Failing the record
-            instead is `conditional.when: fail_record_when_empty`, which excludes a default.
+            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
@@ -2584,11 +2594,14 @@ components:
               empty string renders it as `""` when the extract yields nothing.
               Preserve them verbatim when editing or migrating a mapping — dropping
               the key changes runtime behavior from "use null/empty string as
-              default value" to "do nothing" (field omitted from the output).
+              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 (optionally `conditional.when:
-              extract_not_empty`); use null → `"default": null`; use empty string or
+              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:
@@ -2803,8 +2816,7 @@ components:
 
             **When to Use**
             - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
-              row passes a source array through with a JSONPath `extract` alone or sets
-              `hardCodedValue`
+              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
 
@@ -2888,28 +2900,10 @@ components:
             }
             ```
 
-            **For Arrays of Arrays (arrayarray)**
-            - Similar to objectarray, but inner arrays have empty 'generate' fields
-            - Used for matrix/table structures
-            ```json
-            {
-              "generate": "matrix",
-              "dataType": "arrayarray",
-              "buildArrayHelper": [
-                {
-                  "extract": "$.rows[*]",  // For each row in the rows array
-                  "mappings": [
-                    {
-                      "dataType": "numberarray",  // Note: No generate field for inner arrays
-                      "buildArrayHelper": [
-                        {"extract": "$.rows.columns[*]"}  // Notice: "rows" is singular in the composite object
-                      ]
-                    }
-                  ]
-                }
-              ]
-            }
-            ```
+            **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**
 
@@ -3327,8 +3321,8 @@ components:
         nature is essential for building effective mappings:
 
         1. The schema is self-referential by design - a mapping can contain nested mappings of the same structure
-        2. Complex data structures (nested objects, arrays of objects, arrays of arrays of objects) are ALL
-           handled through this recursive pattern
+        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:
@@ -3382,9 +3376,8 @@ components:
               - 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'
-              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
-                and 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
+              - 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
 
@@ -3401,7 +3394,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              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:
@@ -3435,17 +3430,25 @@ components:
               - `numberarray`: Array of numbers
               - `booleanarray`: Array of booleans
               - `objectarray`: Array of objects (most common array type)
-              - `arrayarray`: Array of arrays (for matrix/table structures)
 
-              Array dataTypes can be populated three ways: pass a source array
-              through unchanged via a JSONPath `extract` alone (when the source is
-              already an array of the right shape), construct/iterate via
-              `buildArrayHelper`, or set a constant with `hardCodedValue`.
+              `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: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
+              - 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.
@@ -3464,7 +3467,6 @@ components:
               - numberarray
               - booleanarray
               - objectarray
-              - arrayarray
             x-enumDescriptions:
               string: Text values; converts other types to their string representation.
               number: Numeric values; attempts conversion from strings.
@@ -3474,7 +3476,6 @@ components:
               numberarray: Array of numeric values.
               booleanarray: Array of boolean values.
               objectarray: Array of objects, the most common array type.
-              arrayarray: Array of arrays, used for matrix or table structures.
             examples:
               - string
               - number
@@ -3517,9 +3518,10 @@ components:
               - 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" must be present
-                for object array datatype), and on a primitive-array row's own
-                `extract` it renders null without an error
+                `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
@@ -3661,8 +3663,10 @@ components:
               Explicit JSON `null` is itself a valid fallback: the destination field is written as
               JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
               action). Omitting the key entirely means no fallback — the field is left out of the
-              output when the extract is empty (the UI's "Do nothing" action). Failing the record
-              instead is `conditional.when: fail_record_when_empty`, which excludes a default.
+              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
@@ -3670,11 +3674,14 @@ components:
                 empty string renders it as `""` when the extract yields nothing.
                 Preserve them verbatim when editing or migrating a mapping — dropping
                 the key changes runtime behavior from "use null/empty string as
-                default value" to "do nothing" (field omitted from the output).
+                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 (optionally `conditional.when:
-                extract_not_empty`); use null → `"default": null`; use empty string or
+                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:
@@ -3889,8 +3896,7 @@ components:
 
               **When to Use**
               - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
-                row passes a source array through with a JSONPath `extract` alone or sets
-                `hardCodedValue`
+                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
 
@@ -3974,28 +3980,10 @@ components:
               }
               ```
 
-              **For Arrays of Arrays (arrayarray)**
-              - Similar to objectarray, but inner arrays have empty 'generate' fields
-              - Used for matrix/table structures
-              ```json
-              {
-                "generate": "matrix",
-                "dataType": "arrayarray",
-                "buildArrayHelper": [
-                  {
-                    "extract": "$.rows[*]",  // For each row in the rows array
-                    "mappings": [
-                      {
-                        "dataType": "numberarray",  // Note: No generate field for inner arrays
-                        "buildArrayHelper": [
-                          {"extract": "$.rows.columns[*]"}  // Notice: "rows" is singular in the composite object
-                        ]
-                      }
-                    ]
-                  }
-                ]
-              }
-              ```
+              **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**
 
@@ -4433,9 +4421,12 @@ components:
           destination-assigned id and `_json.<path>` (or the flattened
           `<path>`) for fields inside the destination's response body. The full
           envelope (including `id`) is present on real runs and in flow-builder
-          previews; flow TEST runs never execute imports, and their mock-built
-          envelope carries no `id` — an `extract: "id"` merges nothing in a test
-          run even though it works on real runs.
+          previews; flow TEST runs never execute imports, and their envelope is
+          built from the import's saved `mockResponse`, or from the placeholder
+          `{"id": "1234567890", "mockResponse": "replace me"}` (numbered
+          `1234567890-1`, `1234567890-2`, … when a page holds several records)
+          — an `extract: "id"` in a test run merges that mock id, never a
+          destination record id.
 
         An `extract` may also be a Handlebars expression. It evaluates against
         the same envelope as a plain path, so every path inside `{{ }}` starts
@@ -5262,7 +5253,7 @@ components:
               - Unmapped Value
               - '{Original Value}'
             x-celigo-ai-guidance:
-              - 'Omit this field entirely when no fallback value is intended. The API rejects an empty string with [invalid_field] Invalid value '''' for field ''default'' — emitting default: "" to mean "no default" fails validation; leaving the key out is the valid spelling of that intent.'
+              - 'Omit this field entirely when no fallback value is intended: a miss the lookup lets through then leaves the mapped field out, and with `allowFailures: false` a miss fails the record whatever the default. An empty string is a value, not "no default" — the save accepts `default: ""`, and an allowed miss writes `""`.'
           allowFailures:
             type:
               - boolean
@@ -5421,6 +5412,11 @@ components:
                   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: