@celigo/api-specs 0.2.29 → 0.2.31

package/dist/sync.yml

@@ -2602,9 +2602,10 @@ paths:
       summary: List supported sync destination applications
       description: |-
         Returns the catalog of applications that can be used as the **destination** of a sync — the
-        data warehouse a sync loads records into. Use the returned `id` as the destination application
-        when building a sync. Identifiers include `snowflake` (Snowflake), `nsaw` (NetSuite
-        Analytics Warehouse), and `bigquery` (Google BigQuery).
+        data warehouse a sync loads records into. A sync's destination application is the type of
+        its destination connection (`rdbms.type` for warehouse connections), which must match one
+        of the returned ids. Identifiers include `snowflake` (Snowflake), `nsaw` (NetSuite
+        Analytics Warehouse), `bigquery` (Google BigQuery), and `mssql` (Microsoft SQL Server).
       tags:
         - Syncs
       operationId: listSyncDestinations
@@ -2629,8 +2630,10 @@ paths:
               examples:
                 default:
                   value:
-                    - id: snowflake
+                    - id: bigquery
+                    - id: mssql
                     - id: nsaw
+                    - id: snowflake
         '401':
           $ref: '#/components/responses/401-unauthorized'
   /v1/di/metadata/connections/{_connectionId}/datasets:
@@ -3848,27 +3851,35 @@ components:
           type: object
           description: |-
             Data warehouse the sync loads records into. Empty (`{}`) on a draft that has no
-            destination yet. Each source + destination host/database/schema combination must
-            be unique across syncs — reusing one fails with `422 duplicate_destination_host` —
-            and all syncs in an integration must target the same destination application type.
+            destination yet. The destination application is the connection's own type
+            (`rdbms.type` for warehouse connections), so `database` and `schema` are read in that
+            application's terms — Google BigQuery treats them as the GCP project and the dataset.
+            Each source + destination host/database/schema combination must be unique across
+            syncs — reusing one fails with `422 duplicate_destination_host` — and all syncs in an
+            integration must target the same destination application type.
           properties:
             _connectionId:
               type: string
               format: objectId
               x-celigo-refModel: connections
               description: |-
-                Connection to the destination warehouse. The application must be one of the
-                supported sync destinations returned by `GET /v1/di/metadata/destinations`.
+                Connection to the destination warehouse. Its application (`rdbms.type` such as
+                `snowflake`, `bigquery` or `mssql`, or a NetSuite Analytics Warehouse JDBC
+                connection) is one of the ids returned by `GET /v1/di/metadata/destinations`.
               examples:
                 - 68d02dbe0839a514623c1d6d
             database:
               type: string
-              description: Database in the destination warehouse the sync loads into.
+              description: |-
+                Database in the destination warehouse the sync loads into. For Google BigQuery this
+                is the GCP project id the tables are created in (`project.dataset.table`).
               examples:
                 - ANALYTICS_DB
             schema:
               type: string
-              description: Schema within `database` where the sync creates and loads tables.
+              description: |-
+                Schema within `database` where the sync creates and loads tables. For Google
+                BigQuery this is the dataset name, with case preserved.
               examples:
                 - salesforce_raw
             tablePrefix:
@@ -4017,27 +4028,60 @@ components:
           description: |-
             Data warehouse the sync loads records into. Omit while drafting; a complete
             destination (connection, database, schema) is required before the sync can be
-            enabled. The source + destination host/database/schema combination must be unique
+            enabled. The destination application is the connection's own type (`rdbms.type`
+            for warehouse connections), so `database` and `schema` are read in that
+            application's terms — Google BigQuery treats them as the GCP project and the
+            dataset. The source + destination host/database/schema combination must be unique
             across syncs (`422 duplicate_destination_host`), and all syncs in an integration
             must target the same destination application type.
+          x-celigo-ai-guidance:
+            - |-
+              Send the block complete or not at all. A partial block is rejected in the destination's
+              own vocabulary with 422 `invalid_destination_sync_config`: `GCP project is required on
+              sync destination` / `BigQuery dataset is required on sync destination` (BigQuery),
+              `SQL Server database is required on sync destination` / `SQL Server schema is required
+              on sync destination` (Microsoft SQL Server). A partial Snowflake block is not caught
+              by validation — the save reaches the warehouse and fails with Snowflake's own
+              `002003` "Database 'UNDEFINED' does not exist" error.
+            - |-
+              Saving a complete destination connects to the warehouse to create the schema
+              (dataset) when it is missing. An unreachable host or unusable credentials fail the
+              save with the connection's error — 422 `invalid_host` for SQL Server,
+              `big_query_unexpected_error` for BigQuery — and no sync document is created or
+              updated; fix the connection rather than changing database or schema names.
+            - |-
+              Microsoft SQL Server validates `database` and `schema` as identifiers (start with a
+              letter or underscore; letters, digits, underscore or `$`; at most 128 characters) and
+              rejects others with 422 `invalid_destination_sync_config`
+              (`SQL Server schema name is invalid: ...`).
           properties:
             _connectionId:
               type: string
               format: objectId
               x-celigo-refModel: connections
               description: |-
-                Connection to the destination warehouse. The application must be one of the
-                supported sync destinations returned by `GET /v1/di/metadata/destinations`.
+                Connection to the destination warehouse. Its application (`rdbms.type` such as
+                `snowflake`, `bigquery` or `mssql`, or a NetSuite Analytics Warehouse JDBC
+                connection) must be one of the ids returned by `GET /v1/di/metadata/destinations`;
+                any other connection fails with `422 invalid_destination_type`.
               examples:
                 - 68d02dbe0839a514623c1d6d
             database:
               type: string
-              description: Database in the destination warehouse the sync loads into.
+              description: |-
+                Database in the destination warehouse the sync loads into; it must already exist.
+                For Google BigQuery this is the GCP project id the tables are created in
+                (`project.dataset.table`).
+              x-celigo-ui-override: For a BigQuery destination the Create Sync wizard shows no database picker and fills this field with the selected connection's rdbms.bigquery.projectId (IO-195900).
               examples:
                 - ANALYTICS_DB
             schema:
               type: string
-              description: Schema within `database` where the sync creates and loads tables.
+              description: |-
+                Schema within `database` where the sync creates and loads tables; created on save
+                when it does not exist. For Google BigQuery this is the dataset name, with case
+                preserved.
+              x-celigo-ui-override: For a BigQuery destination the Create Sync wizard labels this field "dataset" and accepts only letters, digits and underscore (no $), starting with a letter or underscore, at most 1024 characters (IO-195900); Snowflake and NSAW validation is unchanged.
               examples:
                 - salesforce_raw
             tablePrefix:

package/dist/tool.yml

@@ -2075,9 +2075,11 @@ components:
             This field supports THREE DISTINCT PATTERNS that are easily distinguished:
 
             **1. json Path Syntax**
-            - MUST start with '$.' prefix
+            - MUST start with '$' — the record root. An object record is addressed as
+              '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
             - Used for precisely targeting data in structured JSON objects
-            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+              '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
 
             ```json
@@ -2088,7 +2090,8 @@ components:
             - Contains '{{' and '}}' pattern
             - Evaluated by the AFE 2.0 handlebars template engine
             - Can include logic, formatting, and computation
-            - Access input record fields with {{record.fieldName}} notation
+            - Access input record fields with {{record.fieldName}} notation; a grouped
+              (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
             - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
             - Valid on `object`, `objectarray`, and primitive-array dataTypes as
               well as scalars — the rendered template output must parse into the
@@ -2099,7 +2102,7 @@ components:
             ```
 
             **3. Hard-Coded Value (literal string)**
-            - Does NOT start with '$.'
+            - Does NOT start with '$'
             - Does NOT contain handlebars '{{' syntax
             - System treats it as a literal string value
             - VERY COMMON for setting static/constant values
@@ -2121,10 +2124,38 @@ components:
             - The system maintains this context even in deeply nested mappings
             - For object mappings without child mappings, extract should return a complete object
             - When both extract and mappings are defined for objects, extract is applied first
+            - The root is the record as it arrives: an object record roots at `$.field`; a
+              grouped record (an array of rows — grouped exports, file key columns, NetSuite
+              grouped saved searches) roots at the array, so its rows are addressed as
+              `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+              record's shape resolves to nothing without an error.
 
             For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
             For hard-coded values, simply use the literal string as the extract value.
           x-celigo-ai-guidance:
+            - |-
+              ## GROUPED (ARRAY) RECORDS
+              Decide the JSONPath root from the record's shape before writing
+              any extract. When the record is an array of rows, `$.field`,
+              `$.properties.field` and `$.rows[*].field` all resolve to
+              nothing — the processor still reports success and the request
+              body ships as `{}`. Address rows as `$[0].field` (that row's
+              value, typed) or `$[*].field` (every row: joined with commas
+              into a `string` destination; rejected with
+              `incompatible_destination_conversion` into a `number`
+              destination). Column labels with spaces work as
+              `$[*][Order Number]`, `$[*].[Order Number]`, or
+              `$[*]['Order Number']`. For one destination element per row
+              the two array kinds take different helper forms: a primitive
+              array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+              [{"extract": "$[*].field"}]`; an `objectarray` uses
+              `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+              with the children addressing the row relatively (`$.field`,
+              `{{rows.field}}`). An `extract` placed directly on the
+              array-typed field yields nothing. Handlebars
+              extracts bind the array record as `rows` (`{{rows.0.field}}`),
+              an object record as `record`. The reverse holds too: `$[*]` on
+              an object record iterates the object's values, not rows.
             - |-
               ## SIZE LIMIT
               The platform's import save validator caps this field at **1024
@@ -2382,7 +2413,11 @@ components:
               (`$.items[*]`), `"$"` (the record root), or omission — a
               constructed entry (child `mappings` with the extract omitted or
               `"$"`; the two spellings are equivalent) contributes exactly one
-              element, and entries append in order. Indexed or comma-joined
+              element, and entries append in order. On a grouped (array)
+              record the record itself is the array to iterate: `"$[*]"`
+              yields one `objectarray` element per row (children address the
+              row as `$.field`), and `"$[*].field"` yields one primitive-array
+              value per row. Indexed or comma-joined
               entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
               processor renders the entire destination array as null with no
               validation error. To emit a fixed number of static elements, add
@@ -2403,7 +2438,9 @@ components:
 
             **For Simple Arrays (stringarray, numberarray, booleanarray)**
             - Only the 'extract' field is used to pull values
-            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values;
+              on a grouped (array) record the record itself is the array, so the
+              path roots at it ($[*].name — one value per row)
             - Each result is converted to the appropriate primitive type
             ```json
             {
@@ -2505,11 +2542,13 @@ components:
             - When both extract and mappings are provided, the system creates special composite objects
               that maintain hierarchical context during processing
             - This enables accessing both the current array element AND its parent context
-            - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
-              (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
-              instead omits extract or sets it to exactly "$" — never rewrite "$" into a
-              '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
-              the entire destination array as null without raising a validation error
+            - An ITERATING entry's extract MUST be a JSON path that iterates an array:
+              '$.items[*]' when the array is a field of an object record, or '$[*]'
+              (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+              grouped array of rows. A CONSTRUCTED entry (child mappings building one
+              element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+              into an indexed or comma-joined form ('$[0]', '$[0],$[0]'): those render the
+              entire destination array as null without raising a validation error
             - Each array helper entry acts independently, potentially adding multiple elements
 
             The buildArrayHelper is the most complex part of the mappings system - always analyze the
@@ -2923,9 +2962,11 @@ components:
               This field supports THREE DISTINCT PATTERNS that are easily distinguished:
 
               **1. json Path Syntax**
-              - MUST start with '$.' prefix
+              - MUST start with '$' — the record root. An object record is addressed as
+                '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
               - Used for precisely targeting data in structured JSON objects
-              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+                '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
 
               ```json
@@ -2936,7 +2977,8 @@ components:
               - Contains '{{' and '}}' pattern
               - Evaluated by the AFE 2.0 handlebars template engine
               - Can include logic, formatting, and computation
-              - Access input record fields with {{record.fieldName}} notation
+              - Access input record fields with {{record.fieldName}} notation; a grouped
+                (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
               - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
               - Valid on `object`, `objectarray`, and primitive-array dataTypes as
                 well as scalars — the rendered template output must parse into the
@@ -2947,7 +2989,7 @@ components:
               ```
 
               **3. Hard-Coded Value (literal string)**
-              - Does NOT start with '$.'
+              - Does NOT start with '$'
               - Does NOT contain handlebars '{{' syntax
               - System treats it as a literal string value
               - VERY COMMON for setting static/constant values
@@ -2969,10 +3011,38 @@ components:
               - The system maintains this context even in deeply nested mappings
               - For object mappings without child mappings, extract should return a complete object
               - When both extract and mappings are defined for objects, extract is applied first
+              - The root is the record as it arrives: an object record roots at `$.field`; a
+                grouped record (an array of rows — grouped exports, file key columns, NetSuite
+                grouped saved searches) roots at the array, so its rows are addressed as
+                `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+                record's shape resolves to nothing without an error.
 
               For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
               For hard-coded values, simply use the literal string as the extract value.
             x-celigo-ai-guidance:
+              - |-
+                ## GROUPED (ARRAY) RECORDS
+                Decide the JSONPath root from the record's shape before writing
+                any extract. When the record is an array of rows, `$.field`,
+                `$.properties.field` and `$.rows[*].field` all resolve to
+                nothing — the processor still reports success and the request
+                body ships as `{}`. Address rows as `$[0].field` (that row's
+                value, typed) or `$[*].field` (every row: joined with commas
+                into a `string` destination; rejected with
+                `incompatible_destination_conversion` into a `number`
+                destination). Column labels with spaces work as
+                `$[*][Order Number]`, `$[*].[Order Number]`, or
+                `$[*]['Order Number']`. For one destination element per row
+                the two array kinds take different helper forms: a primitive
+                array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+                [{"extract": "$[*].field"}]`; an `objectarray` uses
+                `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+                with the children addressing the row relatively (`$.field`,
+                `{{rows.field}}`). An `extract` placed directly on the
+                array-typed field yields nothing. Handlebars
+                extracts bind the array record as `rows` (`{{rows.0.field}}`),
+                an object record as `record`. The reverse holds too: `$[*]` on
+                an object record iterates the object's values, not rows.
               - |-
                 ## SIZE LIMIT
                 The platform's import save validator caps this field at **1024
@@ -3230,7 +3300,11 @@ components:
                 (`$.items[*]`), `"$"` (the record root), or omission — a
                 constructed entry (child `mappings` with the extract omitted or
                 `"$"`; the two spellings are equivalent) contributes exactly one
-                element, and entries append in order. Indexed or comma-joined
+                element, and entries append in order. On a grouped (array)
+                record the record itself is the array to iterate: `"$[*]"`
+                yields one `objectarray` element per row (children address the
+                row as `$.field`), and `"$[*].field"` yields one primitive-array
+                value per row. Indexed or comma-joined
                 entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
                 processor renders the entire destination array as null with no
                 validation error. To emit a fixed number of static elements, add
@@ -3251,7 +3325,9 @@ components:
 
               **For Simple Arrays (stringarray, numberarray, booleanarray)**
               - Only the 'extract' field is used to pull values
-              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values;
+                on a grouped (array) record the record itself is the array, so the
+                path roots at it ($[*].name — one value per row)
               - Each result is converted to the appropriate primitive type
               ```json
               {
@@ -3353,11 +3429,13 @@ components:
               - When both extract and mappings are provided, the system creates special composite objects
                 that maintain hierarchical context during processing
               - This enables accessing both the current array element AND its parent context
-              - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
-                (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
-                instead omits extract or sets it to exactly "$" — never rewrite "$" into a
-                '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
-                the entire destination array as null without raising a validation error
+              - An ITERATING entry's extract MUST be a JSON path that iterates an array:
+                '$.items[*]' when the array is a field of an object record, or '$[*]'
+                (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+                grouped array of rows. A CONSTRUCTED entry (child mappings building one
+                element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+                into an indexed or comma-joined form ('$[0]', '$[0],$[0]'): those render the
+                entire destination array as null without raising a validation error
               - Each array helper entry acts independently, potentially adding multiple elements
 
               The buildArrayHelper is the most complex part of the mappings system - always analyze the
@@ -4083,6 +4161,16 @@ components:
                   x-enumDescriptions:
                     create: Builds entirely new output records from inputs, ignoring unmapped fields.
                     modify: Makes targeted edits to existing records, preserving unmapped fields.
+                  x-celigo-ai-guidance:
+                    - |-
+                      On a grouped record (the export groups rows, so the record is an
+                      array) only `create` can author output — build it from the rows with
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `modify` has no object to overlay onto an array: the record passes
+                      through untouched and the processor reports success. Either mode
+                      reshapes the inside of one record; neither changes how many records
+                      the page carries (that is the export's `preSavePage` hook) or whether
+                      the export groups at all (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -21772,10 +21860,15 @@ components:
           iterate ``{{#each rows}}``); hook code sees the array as the
           record element and must not assume object shape.
         - |-
-          Transform 2.0 cannot reshape a grouped record at the array root —
-          ``mode: "modify"`` passes the array through untouched and
-          ``mode: "create"`` yields an empty object. Reshape grouped data in
-          a preSavePage hook (or downstream postResponseMap) instead.
+          A grouped record is ONE record: Mapper 2.0 and Transform 2.0 root
+          JSONPath at the array (``$[0].<field>`` / ``$[*].<field>``;
+          ``$.<field>`` resolves nothing), and a Transform 2.0 in ``mode:
+          "create"`` reshapes it in place — header fields from ``$[0]``, a
+          lines array from a ``buildArrayHelper`` over ``$[*]`` (``mode:
+          "modify"`` has no object to overlay and passes the array through
+          untouched). Changing how many records the page carries — each
+          row becoming its own record for every downstream step — is the
+          ``preSavePage`` hook's job alone.
       items:
         type: string
       examples:

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "b36dcff",
-		"generatedAt": "2026-09-18"
+		"iasCommit": "bcdaef7",
+		"generatedAt": "2026-09-19"
 	},
 	"roots": {
 		"aiagent": 133,