@celigo/api-specs 0.2.152 → 0.2.154

package/dist/tool.yml

@@ -3638,6 +3638,12 @@ components:
             - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
               '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
+            - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+              `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+              path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+              need no brackets (`$.Ship To Name`, `$.Tracking #`)
+            - Filter expressions such as `$.items[?(@.active)]` fail the record with
+              "Eval [?(expr)] prevented in JSONPath expression."
 
             ```json
             "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -3826,6 +3832,12 @@ components:
             **Usage**
 
             The lookupName refers to a named lookup defined in the lookups array of the same resource.
+            On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+            is dropped on save. On an import, a name that matches no lookup fails every record
+            with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+            doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+            the field left out, lets the record succeed with the lookup's `default`, or without
+            the mapped field when there is none.
 
             ```json
             {
@@ -4163,6 +4175,11 @@ components:
                   The system creates special composite objects during processing to maintain
                   hierarchical relationships, allowing easy access to both the current array item
                   and its parent contexts.
+
+                  An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                  element per item, with no error. Child extracts drop the `[*]` but keep the
+                  array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                  element-relative `$.sku` reads the record root instead of the element.
                 examples:
                   - $.items[*]
                   - $.order.lineItems[*]
@@ -4374,14 +4391,17 @@ components:
           type: string
           description: |
             **Purpose**
-            Required on every mapping entry. Controls whether the mapping is applied.
+            Controls whether the mapping is applied. Send it on every mapping entry.
 
             **Guidance**
             Only `Active` rows run. `Draft` and `Inactive` rows keep their
             configuration, are saved with minimal validation, and are skipped at
             runtime and in preview; a non-Active parent skips its whole subtree
-            whatever its children say. The API rejects a mapping missing this field
-            (validation error: "Mapping object must have status field present.").
+            whatever its children say. Imports (on save and in the mapper processor)
+            and API response mappings reject a row missing this field (validation
+            error: "Mapping object must have status field present."); a Tool's
+            output mapping saves and runs one, which is why `required` doesn't
+            list it.
           x-celigo-ai-guidance:
             - |-
               Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -4704,6 +4724,12 @@ components:
               - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
                 '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
+              - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+                `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+                path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+                need no brackets (`$.Ship To Name`, `$.Tracking #`)
+              - Filter expressions such as `$.items[?(@.active)]` fail the record with
+                "Eval [?(expr)] prevented in JSONPath expression."
 
               ```json
               "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -4892,6 +4918,12 @@ components:
               **Usage**
 
               The lookupName refers to a named lookup defined in the lookups array of the same resource.
+              On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+              is dropped on save. On an import, a name that matches no lookup fails every record
+              with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+              doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+              the field left out, lets the record succeed with the lookup's `default`, or without
+              the mapped field when there is none.
 
               ```json
               {
@@ -5229,6 +5261,11 @@ components:
                     The system creates special composite objects during processing to maintain
                     hierarchical relationships, allowing easy access to both the current array item
                     and its parent contexts.
+
+                    An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                    element per item, with no error. Child extracts drop the `[*]` but keep the
+                    array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                    element-relative `$.sku` reads the record root instead of the element.
                   examples:
                     - $.items[*]
                     - $.order.lineItems[*]
@@ -5440,14 +5477,17 @@ components:
             type: string
             description: |
               **Purpose**
-              Required on every mapping entry. Controls whether the mapping is applied.
+              Controls whether the mapping is applied. Send it on every mapping entry.
 
               **Guidance**
               Only `Active` rows run. `Draft` and `Inactive` rows keep their
               configuration, are saved with minimal validation, and are skipped at
               runtime and in preview; a non-Active parent skips its whole subtree
-              whatever its children say. The API rejects a mapping missing this field
-              (validation error: "Mapping object must have status field present.").
+              whatever its children say. Imports (on save and in the mapper processor)
+              and API response mappings reject a row missing this field (validation
+              error: "Mapping object must have status field present."); a Tool's
+              output mapping saves and runs one, which is why `required` doesn't
+              list it.
             x-celigo-ai-guidance:
               - |-
                 Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -5818,8 +5858,8 @@ components:
               - Original value indicators: "{Original Value}", "No mapping found"
               - Neutral values: "Other", "N/A", "Miscellaneous"
 
-              If allowFailures is false and no default is specified, the flow will fail
-              when encountering unmapped values.
+              If allowFailures is false, a record whose value is unmapped fails and the default
+              is ignored.
             examples:
               - Unknown
               - Other
@@ -5840,7 +5880,11 @@ components:
               This field determines how the system handles source values that don't exist in the map:
 
               - true: Use the default value for missing mappings and continue processing
-              - false: Treat missing mappings as errors, failing the record
+              - false: Treat missing mappings as errors, failing the record (`lookup_error` for a
+                static map, `lookupcache_evaluation_failed` for a lookup cache)
+              - omitted or null: the record doesn't fail either. On an import a static lookup writes
+                its default if it has one, and a static or cache lookup without one leaves the
+                mapped field out of the output, with no error
 
               **Recommendation**
 
@@ -5854,11 +5898,14 @@ components:
               - All possible source values are known and controlled
               - Missing mappings indicate serious data problems that should be addressed
 
-              The best practice is typically to set allowFailures to true with a meaningful
-              default value, so flows remain operational while alerting you to missing mappings.
+              A default raises no error: records that miss go out with the default value and
+              nothing reports them. Use true only when that fallback is acceptable at the
+              destination, and set false explicitly when a missing value must stop the record.
             examples:
               - true
               - false
+            x-celigo-ai-guidance:
+              - 'Never leave this field out to mean "fail on a miss": on an import, an omitted or null value lets a missing key through without an error (with the default, or without the mapped field when there is none). Only an explicit false fails the record.'
     Transform:
       type: object
       description: |
@@ -7435,7 +7482,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -7472,16 +7519,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -8456,15 +8508,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -8680,9 +8735,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-
@@ -14411,7 +14468,9 @@ components:
 
               - **Field mappings** — a mapping entry sets
                 ``lookupName: "<name>"`` to resolve a field's value through
-                the lookup.
+                the lookup.  A ``lookupName`` that matches no entry in this
+                array fails every record with ``Unable to find lookup in
+                mapping configs - <name>``.
               - **Handlebars expressions** — anywhere handlebars is
                 evaluated (relativeURI, headers, body), ``{{lookup "name"
                 value}}`` calls the lookup with ``value`` as input.
@@ -14425,9 +14484,13 @@ components:
               ## Mirror invariant
 
               The Celigo platform persists lookups in TWO locations on an HTTP
-              import: top-level ``lookups`` and ``http.lookups``.  Both arrays
-              MUST hold byte-for-byte identical content, so write both on
-              every save.
+              import: top-level ``lookups`` and ``http.lookups``, and
+              ``http.lookups`` is the copy that counts.  A save keeps
+              ``http.lookups`` and mirrors it to the top level, overwriting a
+              top-level copy that differs; a ``lookups`` array sent only at the
+              top level is dropped with no error, on create and on PUT, and both
+              arrays read back null.  Write ``http.lookups`` on every save;
+              sending the same array at the top level too is harmless.
             - |-
               ## Static vs dynamic vs cached
 
@@ -14477,12 +14540,13 @@ components:
                   - handlebars
                 description: |
                   Request body template for POST / PUT / PATCH lookup methods, typically
-                  a JSON string with Handlebars placeholders (``{"email":"{{{email}}}"}``);
+                  a JSON string with Handlebars placeholders (``{"email":"{{email}}"}``);
                   ignored for GET / DELETE. The record's fields sit at the top level:
                   ``{{email}}`` renders the record's value, while ``{{record.email}}``
                   renders empty.
                 x-celigo-ai-guidance:
                   - 'Put the lookup''s request template here, not in ``postBody``: a ``postBody`` saves without an error but is not kept under ``http.lookups``, so the lookup goes out with no body and the run reports no error.'
+                  - 'Write string values with double braces inside the quotes (``"{{email}}"``): they are JSON-escaped at runtime. With triple braces a value holding a double quote breaks the request body, and the lookup quietly finds nothing, so an existence check writes the record as new.'
               headers:
                 type: array
                 items:
@@ -14538,10 +14602,17 @@ components:
                   - boolean
                   - 'null'
                 description: |
-                  When true, a lookup miss (no matching response and no
-                  ``default``) resolves to ``null`` and the import continues.
-                  When false (default), a miss halts the record. May be
-                  stored as null (treated as unset).
+                  When true, a lookup miss uses ``default`` (or leaves the mapped
+                  field out when there is none) and the record continues. When
+                  false, a miss fails the record: ``lookup_error`` ("Could not find
+                  value for static lookup: …") for a static ``map``,
+                  ``lookupcache_evaluation_failed`` for a cache. Omitted or null,
+                  a miss doesn't fail the record either: a static lookup writes
+                  its ``default`` if it has one, and a lookup without one (static,
+                  cache, or a live request that matches nothing or fails) leaves
+                  the mapped field out.
+                x-celigo-ai-guidance:
+                  - Set false explicitly when a miss must stop the record. Leaving the field out lets the record through with the default or without the looked-up value, so a destination that needs the real value gets a request without it and nothing errors.
               useDefaultOnMultipleMatches:
                 type: boolean
                 description: |
@@ -24058,7 +24129,7 @@ components:
           description: When true, the mapped value cannot be overwritten by later mapping steps.
         lookupName:
           type: string
-          description: Name of an entry in the import's `lookups` array used to translate the value.
+          description: Name of an entry in the import's `lookups` array (`http.lookups` on an HTTP import) used to translate the value.
           x-celigo-ai-guidance:
             - |-
               Name of a lookup defined on ``resource.lookups`` whose result
@@ -25510,8 +25581,9 @@ components:
 
               Lookups referenced by ``lookupName`` live on the top-level
               ``resource.lookups`` array (mirrored under the adaptor key for
-              adaptors that maintain their own copy — see the mirror invariant
-              on ``lookups``). Lookups are independent of this
+              adaptors that maintain their own copy; on an HTTP import that
+              copy, ``http.lookups``, is the one a save keeps — see the mirror
+              invariant on ``lookups``). Lookups are independent of this
               mapping: they are neither created nor cleared automatically when
               this mapping changes.
           properties:
@@ -25630,6 +25702,12 @@ components:
 
               Both arrays MUST hold byte-for-byte identical content: write
               both on every save and treat them as a single logical field.
+              On an HTTP import the adaptor copy decides: a save keeps
+              ``http.lookups`` and mirrors it here, overwriting a copy here
+              that differs, and an array sent only here is dropped on create
+              and on PUT with no error. A mapping row that names one of its
+              lookups then fails every record with ``Unable to find lookup in
+              mapping configs - <name>``.
             - |-
               ## Shape
 

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "6336cc85",
+		"iasCommit": "6baefd4f",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {