@celigo/api-specs 0.2.7 → 0.2.8

package/dist/ai-agent.yml

@@ -4681,36 +4681,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -4718,27 +4721,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/dist/export.yml

@@ -796,36 +796,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -833,27 +836,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/dist/import.yml

@@ -2016,14 +2016,22 @@ components:
               ### Pattern B — Batch / page wrapper around mapped records
 
               Wrap an envelope (header, version, marketplace, etc.) around
-              a serialized batch.  ``{{#each data}}`` iterates the page;
-              ``{{#each batch_of_records}}`` iterates the page-level batch
-              for ``oneToMany`` imports.
+              a serialized batch.  The template root depends ONLY on
+              ``batchSize`` (live-verified 2026-09-10): with ``batchSize`` 1
+              (the default) the root carries ``record`` (an object record —
+              or the fanned-out child on a ``oneToMany`` import) or ``rows``
+              (a grouped/array record), and ``data`` is the one-element list
+              of records in the request; with ``batchSize`` > 1 the root
+              carries ``batch_of_records`` (one ``{record: …}`` item per
+              record in the request) and ``data`` (the bare records), and
+              ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
+              ``batch_of_records`` appear — children are batched after
+              fan-out under the same rule.
 
               Example shape:
               ``{"values": {{#each data}} {{{jsonSerialize this}}} {{/each}} }``
 
-              Example with comma-separation:
+              Example with comma-separation (``batchSize`` > 1):
               ``[{{#each batch_of_records}}{{{jsonSerialize this.record}}}{{#unless @last}},{{/unless}}{{/each}}]``
 
               ### Pattern C — Custom envelope with per-message fields
@@ -10290,36 +10298,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -10327,27 +10338,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/dist/tool.yml

@@ -10627,14 +10627,22 @@ components:
               ### Pattern B — Batch / page wrapper around mapped records
 
               Wrap an envelope (header, version, marketplace, etc.) around
-              a serialized batch.  ``{{#each data}}`` iterates the page;
-              ``{{#each batch_of_records}}`` iterates the page-level batch
-              for ``oneToMany`` imports.
+              a serialized batch.  The template root depends ONLY on
+              ``batchSize`` (live-verified 2026-09-10): with ``batchSize`` 1
+              (the default) the root carries ``record`` (an object record —
+              or the fanned-out child on a ``oneToMany`` import) or ``rows``
+              (a grouped/array record), and ``data`` is the one-element list
+              of records in the request; with ``batchSize`` > 1 the root
+              carries ``batch_of_records`` (one ``{record: …}`` item per
+              record in the request) and ``data`` (the bare records), and
+              ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
+              ``batch_of_records`` appear — children are batched after
+              fan-out under the same rule.
 
               Example shape:
               ``{"values": {{#each data}} {{{jsonSerialize this}}} {{/each}} }``
 
-              Example with comma-separation:
+              Example with comma-separation (``batchSize`` > 1):
               ``[{{#each batch_of_records}}{{{jsonSerialize this.record}}}{{#unless @last}},{{/unless}}{{/each}}]``
 
               ### Pattern C — Custom envelope with per-message fields
@@ -18632,36 +18640,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -18669,27 +18680,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "ffdb923",
+		"iasCommit": "3f92987",
 		"generatedAt": "2026-09-10"
 	},
 	"roots": {