@celigo/api-specs 0.2.207 → 0.2.209

package/dist/api.yml

@@ -11328,9 +11328,21 @@ components:
                 - COMPUTE_WH
             schema:
               type: string
-              description: |
-                Default Snowflake schema. If omitted, queries must fully-qualify table names
-                (e.g., DATABASE.SCHEMA.TABLE).
+              description: |-
+                Default schema for the session: unqualified table names in queries resolve here, and
+                optimized bulk load imports create their temporary staging table here even when the
+                destination table is schema-qualified — so the connection's role must be able to
+                create that table in it. When blank, optimized bulk load uses PUBLIC.
+              x-celigo-ai-guidance:
+                - |-
+                  When this names a schema the session cannot resolve — Snowflake reports it as not
+                  existing or not authorized for the role, and the session is left without a current
+                  schema — every optimized bulk load fails at the staging step with code `query_fail`
+                  and the message "Failed to run the bulk load query. Err: [TempTableQuery] The
+                  provided schema is invalid: <this value>" (the connector's rewrite of Snowflake's
+                  "This session does not have a current schema"). Fix: set this to a schema the role
+                  can create the staging table in — normally the destination table's own schema — or
+                  point the import at a second Snowflake connection with that default schema.
               examples:
                 - PUBLIC
             role:

package/dist/connection.yml

@@ -7161,9 +7161,21 @@ components:
                 - COMPUTE_WH
             schema:
               type: string
-              description: |
-                Default Snowflake schema. If omitted, queries must fully-qualify table names
-                (e.g., DATABASE.SCHEMA.TABLE).
+              description: |-
+                Default schema for the session: unqualified table names in queries resolve here, and
+                optimized bulk load imports create their temporary staging table here even when the
+                destination table is schema-qualified — so the connection's role must be able to
+                create that table in it. When blank, optimized bulk load uses PUBLIC.
+              x-celigo-ai-guidance:
+                - |-
+                  When this names a schema the session cannot resolve — Snowflake reports it as not
+                  existing or not authorized for the role, and the session is left without a current
+                  schema — every optimized bulk load fails at the staging step with code `query_fail`
+                  and the message "Failed to run the bulk load query. Err: [TempTableQuery] The
+                  provided schema is invalid: <this value>" (the connector's rewrite of Snowflake's
+                  "This session does not have a current schema"). Fix: set this to a schema the role
+                  can create the staging table in — normally the destination table's own schema — or
+                  point the import at a second Snowflake connection with that default schema.
               examples:
                 - PUBLIC
             role:

package/dist/enduser.yml

@@ -5186,9 +5186,21 @@ components:
                 - COMPUTE_WH
             schema:
               type: string
-              description: |
-                Default Snowflake schema. If omitted, queries must fully-qualify table names
-                (e.g., DATABASE.SCHEMA.TABLE).
+              description: |-
+                Default schema for the session: unqualified table names in queries resolve here, and
+                optimized bulk load imports create their temporary staging table here even when the
+                destination table is schema-qualified — so the connection's role must be able to
+                create that table in it. When blank, optimized bulk load uses PUBLIC.
+              x-celigo-ai-guidance:
+                - |-
+                  When this names a schema the session cannot resolve — Snowflake reports it as not
+                  existing or not authorized for the role, and the session is left without a current
+                  schema — every optimized bulk load fails at the staging step with code `query_fail`
+                  and the message "Failed to run the bulk load query. Err: [TempTableQuery] The
+                  provided schema is invalid: <this value>" (the connector's rewrite of Snowflake's
+                  "This session does not have a current schema"). Fix: set this to a schema the role
+                  can create the staging table in — normally the destination table's own schema — or
+                  point the import at a second Snowflake connection with that default schema.
               examples:
                 - PUBLIC
             role:

package/dist/export.yml

@@ -16424,7 +16424,9 @@ components:
         `POST /v1/exports/preview` reads the `mockOutput` in its request body, not the saved one. For
         an export the preview supports (an HTTP export, for example), a body that carries it (as an
         export read back with GET does) returns that snapshot as a lone `parse` stage without calling
-        the source; remove `mockOutput` from the body to preview live records.
+        the source; remove `mockOutput` from the body to preview live records. A body mock with an
+        empty or missing `page_of_records` still skips the source and returns 200 with empty `data`
+        and an empty `parse` stage.
 
         **Limitations**
 
@@ -17989,17 +17991,27 @@ components:
         dataURIs:
           type: array
           description: |-
-            URIs for any files produced by the preview (e.g. file-based exports
-            writing to cloud storage). Empty for non-file adaptors.
+            Links to the records in the source system. On an export preview, one
+            entry per record in `data`: a link to the record when one is available
+            (for example the export's `dataURITemplate` rendered for that record),
+            otherwise `null`, as on an HTTP export without a template; absent when
+            the preview returned no records and when a `mockOutput` in the request
+            body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         dataRecordTraceKeys:
           type: array
           description: |-
             Trace keys for the records in this preview — one per record,
-            correlating stage outputs to their source record.
+            correlating stage outputs to their source record; `null` for a record
+            that has no key. Absent when the preview returned no records and
+            captured no keys, and when a `mockOutput` in the request body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         stages:
           type: array
           description: |-
@@ -18062,12 +18074,11 @@ components:
             type: object
             additionalProperties: true
         traceKeysDuplicate:
-          type: array
+          type: boolean
           description: |-
-            Trace keys that collided during the preview — a diagnostic for
-            trace-key generation; rarely non-empty in practice.
-          items:
-            type: string
+            When true, two or more records in this preview share a trace key, so
+            the export's `traceKeyTemplate` does not identify records uniquely.
+            Absent whenever `dataRecordTraceKeys` is absent.
     PreviewRequest:
       type: object
       description: Request body for previewing export data

package/dist/flow.yml

@@ -8824,17 +8824,27 @@ components:
         dataURIs:
           type: array
           description: |-
-            URIs for any files produced by the preview (e.g. file-based exports
-            writing to cloud storage). Empty for non-file adaptors.
+            Links to the records in the source system. On an export preview, one
+            entry per record in `data`: a link to the record when one is available
+            (for example the export's `dataURITemplate` rendered for that record),
+            otherwise `null`, as on an HTTP export without a template; absent when
+            the preview returned no records and when a `mockOutput` in the request
+            body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         dataRecordTraceKeys:
           type: array
           description: |-
             Trace keys for the records in this preview — one per record,
-            correlating stage outputs to their source record.
+            correlating stage outputs to their source record; `null` for a record
+            that has no key. Absent when the preview returned no records and
+            captured no keys, and when a `mockOutput` in the request body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         stages:
           type: array
           description: |-
@@ -8897,12 +8907,11 @@ components:
             type: object
             additionalProperties: true
         traceKeysDuplicate:
-          type: array
+          type: boolean
           description: |-
-            Trace keys that collided during the preview — a diagnostic for
-            trace-key generation; rarely non-empty in practice.
-          items:
-            type: string
+            When true, two or more records in this preview share a trace key, so
+            the export's `traceKeyTemplate` does not identify records uniquely.
+            Absent whenever `dataRecordTraceKeys` is absent.
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.

package/dist/import.yml

@@ -5681,6 +5681,7 @@ components:
               description: |-
                 Target table for the bulk load.
                 Must reference an existing table accessible with the connection's credentials; schema-qualified names are supported.
+                On Snowflake, the temporary staging table that precedes the load is created in the connection's default schema (`rdbms.snowflake.schema` on the connection), not in this table's schema.
               x-celigo-ai-guidance:
                 - |-
                   The name of the target table within the relational database management system
@@ -8899,6 +8900,11 @@ components:
               - Use `"csv"` for flat tabular data, spreadsheet-like records
               - Use `"xml"` for XML-based integrations, SOAP services
               - Use `"xlsx"` for Excel-compatible outputs
+            - |-
+              What writes the file's content differs by type: `csv` and `xlsx` are mapping-driven
+              (the mapped record's fields become the columns); `json` is mapping-driven too unless
+              `json.body` is set; `xml` always needs the `xml.body` template; `filedefinition` takes
+              the file definition's rules. Pick the type first, then author only that type's block.
         encoding:
           type: string
           enum:
@@ -9040,6 +9046,41 @@ components:
           type: object
           description: JSON-specific configuration. Only used when `type` is `"json"`.
           properties:
+            body:
+              type: string
+              x-celigo-agent:
+                - handlebars
+              description: |-
+                Handlebars template for the generated JSON document — the *Build JSON document*
+                editor. Rendered once per file against the records of the page, after the mapping:
+                text before the `{{#each batch_of_records}}` loop is the file's header, the loop
+                body is written once per record, text after it is the footer; under
+                `aggregation.type: all` the loop's output for every page of the run is written
+                between one header and one footer. Omit it to write the mapped records as a JSON
+                array per file.
+              x-celigo-ai-guidance:
+                - |-
+                  Leave this out unless the user needs a custom document shape: with no body the
+                  platform writes each file as a JSON array of the mapped records. A saved body
+                  overrides that — a leftover `{}` body writes literal `{}` files.
+                - |-
+                  When a body is needed, wrap the per-record part in `{{#each batch_of_records}} …
+                  {{/each}}` and address the record inside it as `record.<field>` (a grouped record
+                  as `{{#each rows}} … {{/each}}`); `{{{jsonSerialize record}}}` with
+                  `{{#unless @last}},{{/unless}}` between elements is the common form. The JSON
+                  generator recognises only that loop: a `{{#each data}}` loop is written whole per
+                  page and the pages are joined with commas (`[…],[…]`, invalid JSON under one file
+                  per run). At the root there is no `record`: `{{record.<field>}}` or a bare
+                  `{{<field>}}` outside the loop renders empty, while `batch_of_records` is in
+                  scope (`batch_of_records.0.record.<field>` is the first record when a header needs
+                  it). A body with no loop is rendered whole once per page — `{"id": {{record.id}} }`
+                  becomes `{"id":  }` per page — and under `aggregation.type: all` the pages are
+                  joined with commas (`{"id":  },{"id":  }`), which is invalid JSON even when each
+                  page's own text was valid.
+                - |-
+                  The template renders against the page whatever `http.batchSize` says, and `http.body`
+                  plays no part in the file's content. The field's editor Preview does not run the
+                  generator, so judge the body by a run.
             resourcePath:
               type: string
               description: JSONPath expression to locate records within the JSON structure.
@@ -9047,6 +9088,39 @@ components:
           type: object
           description: XML-specific configuration. Only used when `type` is `"xml"`.
           properties:
+            body:
+              type: string
+              x-celigo-agent:
+                - handlebars
+              description: |-
+                Handlebars template for the generated XML document — the *Build XML document*
+                editor. Rendered once per file against the records of the page, after the mapping:
+                text before the record loop is the file's header, the loop body is written once per
+                record, text after it is the footer; under `aggregation.type: all` the loop's
+                output for every page of the run is written between one header and one footer.
+                Must be set when `type` is `"xml"` — there is no mapping-driven XML.
+              x-celigo-ai-guidance:
+                - |-
+                  Author it as header + record loop + footer: the XML declaration and root element
+                  around `{{#each batch_of_records}} … {{/each}}`, with the record addressed inside
+                  the loop as `record.<field>` (a grouped record as `{{#each rows}} … {{/each}}`,
+                  nested elements as `{{#each record.<list>}} … {{/each}}`). The XML generator also
+                  accepts the legacy `{{#each data}} … {{/each}}`, which binds the record itself as
+                  `this` (`{{<field>}}`). At the root there is no `record`: `{{record.<field>}}` or
+                  a bare `{{<field>}}` outside the loop renders empty, while `batch_of_records` is in
+                  scope (`batch_of_records.0.record.<field>` is the first record when a header needs
+                  it). A body with no loop is rendered whole once per page — `<root>{{record.id}}</root>`
+                  becomes `<root></root>` per page — and under `aggregation.type: all` the pages are
+                  concatenated into one multi-root file (`<root></root><root></root>`); the import
+                  form does not let a one-file-per-run XML template without an each block save,
+                  while an API save writes that file.
+                - |-
+                  The template renders against the page whatever `http.batchSize` says, and on an
+                  HTTP file-provider import `http.body` plays no part in the file's content. The
+                  field's editor Preview does not run the generator, so judge the body by a run.
+                - |-
+                  Saving `type: xml` without this field fails with 422 `missing_required_field`
+                  ("required field, file.xml.body is missing.").
             resourcePath:
               type: string
               description: XPath expression to locate records within the XML structure.
@@ -9337,6 +9411,19 @@ components:
               description: Provider-native ID of the storage root the backup relative path resolves against; set when pathMode is relativePath.
               examples:
                 - 1qU1hvFarBFMb4-twqKm1rR5o_6j9vs9g
+      if:
+        properties:
+          type:
+            const: xml
+        required:
+          - type
+      then:
+        required:
+          - xml
+        properties:
+          xml:
+            required:
+              - body
     FileSystem:
       type: object
       description: |-

package/dist/mcp-server.yml

@@ -8103,9 +8103,21 @@ components:
                 - COMPUTE_WH
             schema:
               type: string
-              description: |
-                Default Snowflake schema. If omitted, queries must fully-qualify table names
-                (e.g., DATABASE.SCHEMA.TABLE).
+              description: |-
+                Default schema for the session: unqualified table names in queries resolve here, and
+                optimized bulk load imports create their temporary staging table here even when the
+                destination table is schema-qualified — so the connection's role must be able to
+                create that table in it. When blank, optimized bulk load uses PUBLIC.
+              x-celigo-ai-guidance:
+                - |-
+                  When this names a schema the session cannot resolve — Snowflake reports it as not
+                  existing or not authorized for the role, and the session is left without a current
+                  schema — every optimized bulk load fails at the staging step with code `query_fail`
+                  and the message "Failed to run the bulk load query. Err: [TempTableQuery] The
+                  provided schema is invalid: <this value>" (the connector's rewrite of Snowflake's
+                  "This session does not have a current schema"). Fix: set this to a schema the role
+                  can create the staging table in — normally the destination table's own schema — or
+                  point the import at a second Snowflake connection with that default schema.
               examples:
                 - PUBLIC
             role:

package/dist/tool.yml

@@ -10658,9 +10658,21 @@ components:
                 - COMPUTE_WH
             schema:
               type: string
-              description: |
-                Default Snowflake schema. If omitted, queries must fully-qualify table names
-                (e.g., DATABASE.SCHEMA.TABLE).
+              description: |-
+                Default schema for the session: unqualified table names in queries resolve here, and
+                optimized bulk load imports create their temporary staging table here even when the
+                destination table is schema-qualified — so the connection's role must be able to
+                create that table in it. When blank, optimized bulk load uses PUBLIC.
+              x-celigo-ai-guidance:
+                - |-
+                  When this names a schema the session cannot resolve — Snowflake reports it as not
+                  existing or not authorized for the role, and the session is left without a current
+                  schema — every optimized bulk load fails at the staging step with code `query_fail`
+                  and the message "Failed to run the bulk load query. Err: [TempTableQuery] The
+                  provided schema is invalid: <this value>" (the connector's rewrite of Snowflake's
+                  "This session does not have a current schema"). Fix: set this to a schema the role
+                  can create the staging table in — normally the destination table's own schema — or
+                  point the import at a second Snowflake connection with that default schema.
               examples:
                 - PUBLIC
             role:
@@ -17556,6 +17568,7 @@ components:
               description: |-
                 Target table for the bulk load.
                 Must reference an existing table accessible with the connection's credentials; schema-qualified names are supported.
+                On Snowflake, the temporary staging table that precedes the load is created in the connection's default schema (`rdbms.snowflake.schema` on the connection), not in this table's schema.
               x-celigo-ai-guidance:
                 - |-
                   The name of the target table within the relational database management system
@@ -20774,6 +20787,11 @@ components:
               - Use `"csv"` for flat tabular data, spreadsheet-like records
               - Use `"xml"` for XML-based integrations, SOAP services
               - Use `"xlsx"` for Excel-compatible outputs
+            - |-
+              What writes the file's content differs by type: `csv` and `xlsx` are mapping-driven
+              (the mapped record's fields become the columns); `json` is mapping-driven too unless
+              `json.body` is set; `xml` always needs the `xml.body` template; `filedefinition` takes
+              the file definition's rules. Pick the type first, then author only that type's block.
         encoding:
           type: string
           enum:
@@ -20915,6 +20933,41 @@ components:
           type: object
           description: JSON-specific configuration. Only used when `type` is `"json"`.
           properties:
+            body:
+              type: string
+              x-celigo-agent:
+                - handlebars
+              description: |-
+                Handlebars template for the generated JSON document — the *Build JSON document*
+                editor. Rendered once per file against the records of the page, after the mapping:
+                text before the `{{#each batch_of_records}}` loop is the file's header, the loop
+                body is written once per record, text after it is the footer; under
+                `aggregation.type: all` the loop's output for every page of the run is written
+                between one header and one footer. Omit it to write the mapped records as a JSON
+                array per file.
+              x-celigo-ai-guidance:
+                - |-
+                  Leave this out unless the user needs a custom document shape: with no body the
+                  platform writes each file as a JSON array of the mapped records. A saved body
+                  overrides that — a leftover `{}` body writes literal `{}` files.
+                - |-
+                  When a body is needed, wrap the per-record part in `{{#each batch_of_records}} …
+                  {{/each}}` and address the record inside it as `record.<field>` (a grouped record
+                  as `{{#each rows}} … {{/each}}`); `{{{jsonSerialize record}}}` with
+                  `{{#unless @last}},{{/unless}}` between elements is the common form. The JSON
+                  generator recognises only that loop: a `{{#each data}}` loop is written whole per
+                  page and the pages are joined with commas (`[…],[…]`, invalid JSON under one file
+                  per run). At the root there is no `record`: `{{record.<field>}}` or a bare
+                  `{{<field>}}` outside the loop renders empty, while `batch_of_records` is in
+                  scope (`batch_of_records.0.record.<field>` is the first record when a header needs
+                  it). A body with no loop is rendered whole once per page — `{"id": {{record.id}} }`
+                  becomes `{"id":  }` per page — and under `aggregation.type: all` the pages are
+                  joined with commas (`{"id":  },{"id":  }`), which is invalid JSON even when each
+                  page's own text was valid.
+                - |-
+                  The template renders against the page whatever `http.batchSize` says, and `http.body`
+                  plays no part in the file's content. The field's editor Preview does not run the
+                  generator, so judge the body by a run.
             resourcePath:
               type: string
               description: JSONPath expression to locate records within the JSON structure.
@@ -20922,6 +20975,39 @@ components:
           type: object
           description: XML-specific configuration. Only used when `type` is `"xml"`.
           properties:
+            body:
+              type: string
+              x-celigo-agent:
+                - handlebars
+              description: |-
+                Handlebars template for the generated XML document — the *Build XML document*
+                editor. Rendered once per file against the records of the page, after the mapping:
+                text before the record loop is the file's header, the loop body is written once per
+                record, text after it is the footer; under `aggregation.type: all` the loop's
+                output for every page of the run is written between one header and one footer.
+                Must be set when `type` is `"xml"` — there is no mapping-driven XML.
+              x-celigo-ai-guidance:
+                - |-
+                  Author it as header + record loop + footer: the XML declaration and root element
+                  around `{{#each batch_of_records}} … {{/each}}`, with the record addressed inside
+                  the loop as `record.<field>` (a grouped record as `{{#each rows}} … {{/each}}`,
+                  nested elements as `{{#each record.<list>}} … {{/each}}`). The XML generator also
+                  accepts the legacy `{{#each data}} … {{/each}}`, which binds the record itself as
+                  `this` (`{{<field>}}`). At the root there is no `record`: `{{record.<field>}}` or
+                  a bare `{{<field>}}` outside the loop renders empty, while `batch_of_records` is in
+                  scope (`batch_of_records.0.record.<field>` is the first record when a header needs
+                  it). A body with no loop is rendered whole once per page — `<root>{{record.id}}</root>`
+                  becomes `<root></root>` per page — and under `aggregation.type: all` the pages are
+                  concatenated into one multi-root file (`<root></root><root></root>`); the import
+                  form does not let a one-file-per-run XML template without an each block save,
+                  while an API save writes that file.
+                - |-
+                  The template renders against the page whatever `http.batchSize` says, and on an
+                  HTTP file-provider import `http.body` plays no part in the file's content. The
+                  field's editor Preview does not run the generator, so judge the body by a run.
+                - |-
+                  Saving `type: xml` without this field fails with 422 `missing_required_field`
+                  ("required field, file.xml.body is missing.").
             resourcePath:
               type: string
               description: XPath expression to locate records within the XML structure.
@@ -21212,6 +21298,19 @@ components:
               description: Provider-native ID of the storage root the backup relative path resolves against; set when pathMode is relativePath.
               examples:
                 - 1qU1hvFarBFMb4-twqKm1rR5o_6j9vs9g
+      if:
+        properties:
+          type:
+            const: xml
+        required:
+          - type
+      then:
+        required:
+          - xml
+        properties:
+          xml:
+            required:
+              - body
     FileSystem:
       type: object
       description: |-
@@ -38239,7 +38338,9 @@ components:
         `POST /v1/exports/preview` reads the `mockOutput` in its request body, not the saved one. For
         an export the preview supports (an HTTP export, for example), a body that carries it (as an
         export read back with GET does) returns that snapshot as a lone `parse` stage without calling
-        the source; remove `mockOutput` from the body to preview live records.
+        the source; remove `mockOutput` from the body to preview live records. A body mock with an
+        empty or missing `page_of_records` still skips the source and returns 200 with empty `data`
+        and an empty `parse` stage.
 
         **Limitations**
 

package/package.json

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