@celigo/api-specs 0.2.154 → 0.2.155

package/dist/export.yml

@@ -12404,9 +12404,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
 
@@ -12423,7 +12422,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:
@@ -12457,17 +12458,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.
@@ -12486,7 +12495,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.
@@ -12496,7 +12504,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
@@ -12539,9 +12546,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
@@ -12683,8 +12691,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
@@ -12692,11 +12702,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:
@@ -12911,8 +12924,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
 
@@ -12996,28 +13008,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**
 
@@ -13435,8 +13429,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:
@@ -13490,9 +13484,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
 
@@ -13509,7 +13502,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:
@@ -13543,17 +13538,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.
@@ -13572,7 +13575,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.
@@ -13582,7 +13584,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
@@ -13625,9 +13626,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
@@ -13769,8 +13771,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
@@ -13778,11 +13782,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:
@@ -13997,8 +14004,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
 
@@ -14082,28 +14088,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**
 
@@ -14747,7 +14735,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
@@ -14906,6 +14894,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:

package/dist/flow.yml

@@ -4349,9 +4349,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

package/dist/httpconnectorendpoint.yml

@@ -836,7 +836,22 @@ components:
           description: |-
             How the connector framework turns this endpoint into an export or an
             import: which one it becomes, the fields it pre-configures, and the
-            fields the user must still fill in.
+            fields the user must still fill in. Each entry's `path` names a setting
+            in the connector's form, which is not always a literal path on the
+            generated export or import.
+          x-celigo-ai-guidance:
+            - |-
+              Read against the published Shopify connector on 2026-10-21: the list-customers export
+              endpoint presets `response` to `{resourcePath: "customers"}` and also presets `delta`,
+              and asks for `type` (`delta` or `test`); the create-customer import endpoint asks for
+              `ignoreExisting` and for `mapping.fields.generate.customer.email`, `…first_name` and
+              `…last_name`.
+            - |-
+              Copy a path that is already a field of the step (`type`, `ignoreExisting`,
+              `http.response.resourcePath`). Set a form group such as `response` through the step
+              fields its value names (`{resourcePath: "customers"}` is `http.response.resourcePath`).
+              Treat `mapping.fields.generate.<field>` as a destination field the import's mapping must
+              produce, not a property to set.
           required:
             - type
           properties:

package/dist/httpconnectorresource.yml

@@ -1080,9 +1080,14 @@ components:
             properties:
               path:
                 type: string
-                description: Dot-notation path of the field on the generated export or import.
+                description: |-
+                  Dot-notation name of the setting in the connector's form. It is not always a literal
+                  path on the generated export or import: a form group such as `response` takes an
+                  object value (`{resourcePath: "customers"}`) that sets the step's
+                  `http.response.resourcePath`.
                 examples:
                   - http.successMediaType
+                  - response
               values:
                 type: array
                 description: Value(s) to assign. Typically a single-element array; entries may be any JSON type.
@@ -1104,9 +1109,14 @@ components:
             properties:
               path:
                 type: string
-                description: Dot-notation path of the field on the generated export or import.
+                description: |-
+                  Dot-notation name of the setting the connector's form asks for: a step field such as
+                  `ignoreExisting` or `type`, or `mapping.fields.generate.<field>`, a destination field
+                  the import's mapping must produce.
                 examples:
                   - name
+                  - ignoreExisting
+                  - mapping.fields.generate.customer.email
               values:
                 type: array
                 description: Optional suggested or constrained values. Entries may be any JSON type.