@celigo/api-specs 0.2.1 → 0.2.2

package/dist/ai-agent.yml

@@ -3428,8 +3428,10 @@ components:
 
         - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
           "errors": []}` — `data` holds the records the lookup returned, so
-          extracts must start from it (e.g. `data[0].name`). A bare result-record
-          field name (e.g. `name`) resolves to nothing and merges nothing.
+          extracts must start from it: `data[0].name` copies a field of the
+          first result, `data` copies the whole result array. A bare
+          result-record field name (e.g. `name`) resolves to nothing and merges
+          nothing.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
           "ignored": false, "errors": [], "_json": <raw destination response>}` —
           use `id` for the destination-assigned id and `_json.<path>` for fields
@@ -3449,11 +3451,26 @@ components:
           responseMapping is fully replaced on PUT: omitting it resets the step
           to empty `{"fields": [], "lists": []}`. Always send the complete
           intended mapping for every step.
+        - |-
+          To carry several lookup results onto the record, use `extract: "data"`
+          (the whole result array) or a `lists` entry whose extracts use
+          `data[*].x` — never `data[*].x` in `fields[].extract`, which merges
+          nothing: the record simply never gains the field.
       examples:
         - fields:
             - extract: id
               generate: ContactId
           lists: []
+        - fields:
+            - extract: data[0].customer.name
+              generate: customerName
+          lists:
+            - generate: matchedOrders
+              fields:
+                - extract: data[*].id
+                  generate: orderId
+                - extract: data[*].total
+                  generate: amount
       properties:
         fields:
           type: array
@@ -3468,13 +3485,17 @@ components:
                 description: |
                   Path within the canonical response envelope to copy the value
                   from. For lookup steps, paths start from the envelope's `data`
-                  array (`data[0].x` and `data.0.x` are equivalent); for import
-                  steps, use the envelope fields `id`, `statusCode`, `ignored`,
-                  or `_json.<path>` for the raw response body. Paths that skip
-                  the envelope (bare response field names) resolve to nothing.
+                  array (`data[0].x` and `data.0.x` are equivalent; `data` alone
+                  copies every result); for import steps, use the envelope fields
+                  `id`, `statusCode`, `ignored`, or `_json.<path>` for the raw
+                  response body. Paths that skip the envelope (bare response
+                  field names) resolve to nothing, and a `[*]` wildcard is not
+                  honored here — `data[*].x` merges nothing; iterate arrays with
+                  `lists` instead.
                 examples:
                   - data[0].customer.name
                   - data.0.fields.Product Name
+                  - data
                   - id
                   - _json.orderNumber
               generate:
@@ -3492,8 +3513,10 @@ components:
           description: |
             Array mappings that build a target array on the in-flight record
             from an array inside the response envelope — one output item per
-            response item. Not needed for one-to-many (fan-out) merge-back,
-            which uses plain field mappings.
+            element of the array the item extracts mark with `[*]` (`data[*].x`
+            for lookups, `_json.<arrayPath>[*].x` for imports); an empty source
+            array yields an empty target array. Not needed for one-to-many
+            (fan-out) merge-back, which uses plain field mappings.
           items:
             type: object
             properties:
@@ -3517,12 +3540,16 @@ components:
                     extract:
                       type: string
                       description: |
-                        Source field within each response-array item, relative
-                        to the item itself.
+                        Full envelope path to the source value, with `[*]`
+                        marking the array to iterate — `data[*].productId` for a
+                        lookup, `_json.items[*].sku` for an import. A path without
+                        `[*]` (e.g. `statusCode`) repeats the same envelope value
+                        on every item; an item-relative name (`productId`)
+                        resolves to nothing and produces empty objects.
                       examples:
-                        - productId
-                        - quantity
-                        - price
+                        - data[*].productId
+                        - data[*].quantity
+                        - _json.items[*].sku
                     generate:
                       type: string
                       description: Target field within each mapped array item.

package/dist/flow.yml

@@ -4079,8 +4079,10 @@ components:
 
         - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
           "errors": []}` — `data` holds the records the lookup returned, so
-          extracts must start from it (e.g. `data[0].name`). A bare result-record
-          field name (e.g. `name`) resolves to nothing and merges nothing.
+          extracts must start from it: `data[0].name` copies a field of the
+          first result, `data` copies the whole result array. A bare
+          result-record field name (e.g. `name`) resolves to nothing and merges
+          nothing.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
           "ignored": false, "errors": [], "_json": <raw destination response>}` —
           use `id` for the destination-assigned id and `_json.<path>` for fields
@@ -4100,11 +4102,26 @@ components:
           responseMapping is fully replaced on PUT: omitting it resets the step
           to empty `{"fields": [], "lists": []}`. Always send the complete
           intended mapping for every step.
+        - |-
+          To carry several lookup results onto the record, use `extract: "data"`
+          (the whole result array) or a `lists` entry whose extracts use
+          `data[*].x` — never `data[*].x` in `fields[].extract`, which merges
+          nothing: the record simply never gains the field.
       examples:
         - fields:
             - extract: id
               generate: ContactId
           lists: []
+        - fields:
+            - extract: data[0].customer.name
+              generate: customerName
+          lists:
+            - generate: matchedOrders
+              fields:
+                - extract: data[*].id
+                  generate: orderId
+                - extract: data[*].total
+                  generate: amount
       properties:
         fields:
           type: array
@@ -4119,13 +4136,17 @@ components:
                 description: |
                   Path within the canonical response envelope to copy the value
                   from. For lookup steps, paths start from the envelope's `data`
-                  array (`data[0].x` and `data.0.x` are equivalent); for import
-                  steps, use the envelope fields `id`, `statusCode`, `ignored`,
-                  or `_json.<path>` for the raw response body. Paths that skip
-                  the envelope (bare response field names) resolve to nothing.
+                  array (`data[0].x` and `data.0.x` are equivalent; `data` alone
+                  copies every result); for import steps, use the envelope fields
+                  `id`, `statusCode`, `ignored`, or `_json.<path>` for the raw
+                  response body. Paths that skip the envelope (bare response
+                  field names) resolve to nothing, and a `[*]` wildcard is not
+                  honored here — `data[*].x` merges nothing; iterate arrays with
+                  `lists` instead.
                 examples:
                   - data[0].customer.name
                   - data.0.fields.Product Name
+                  - data
                   - id
                   - _json.orderNumber
               generate:
@@ -4143,8 +4164,10 @@ components:
           description: |
             Array mappings that build a target array on the in-flight record
             from an array inside the response envelope — one output item per
-            response item. Not needed for one-to-many (fan-out) merge-back,
-            which uses plain field mappings.
+            element of the array the item extracts mark with `[*]` (`data[*].x`
+            for lookups, `_json.<arrayPath>[*].x` for imports); an empty source
+            array yields an empty target array. Not needed for one-to-many
+            (fan-out) merge-back, which uses plain field mappings.
           items:
             type: object
             properties:
@@ -4168,12 +4191,16 @@ components:
                     extract:
                       type: string
                       description: |
-                        Source field within each response-array item, relative
-                        to the item itself.
+                        Full envelope path to the source value, with `[*]`
+                        marking the array to iterate — `data[*].productId` for a
+                        lookup, `_json.items[*].sku` for an import. A path without
+                        `[*]` (e.g. `statusCode`) repeats the same envelope value
+                        on every item; an item-relative name (`productId`)
+                        resolves to nothing and produces empty objects.
                       examples:
-                        - productId
-                        - quantity
-                        - price
+                        - data[*].productId
+                        - data[*].quantity
+                        - _json.items[*].sku
                     generate:
                       type: string
                       description: Target field within each mapped array item.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "files": [

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "cb9d158",
-		"generatedAt": "2026-08-31"
+		"iasCommit": "ae8d0a4",
+		"generatedAt": "2026-09-04"
 	},
 	"roots": {
 		"aiagent": 121,