@celigo/api-specs 0.2.83 → 0.2.84

package/dist/asynchelper.yml

@@ -769,7 +769,8 @@ components:
             Explicit JSON `null` is itself a valid fallback: the destination field is written as
             JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
             action). Omitting the key entirely means no fallback — the field is left out of the
-            output when the extract is empty (the UI's "Do nothing" action).
+            output when the extract is empty (the UI's "Do nothing" action). Failing the record
+            instead is `conditional.when: fail_record_when_empty`, which excludes a default.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
@@ -778,6 +779,12 @@ components:
               Preserve them verbatim when editing or migrating a mapping — dropping
               the key changes runtime behavior from "use null/empty string as
               default value" to "do nothing" (field omitted from the output).
+            - |-
+              The four "Action to take if source field has no value" choices map to:
+              do nothing → no `default` key (optionally `conditional.when:
+              extract_not_empty`); use null → `"default": null`; use empty string or
+              a custom value → `"default": "<value>"`; cause the record to fail →
+              `conditional.when: fail_record_when_empty` with no `default` key.
           examples:
             - N/A
             - '0'
@@ -1110,6 +1117,22 @@ components:
                   - $.order.lineItems[*]
                   - $.parents[*].children[*]
                   - $
+              name:
+                type: string
+                maxLength: 200
+                description: |
+                  Display label for this source object in the mapper, so the sources of
+                  an object array can be told apart instead of all showing as `$`.
+                  Has no effect at runtime; stored only when non-empty.
+                x-celigo-ai-guidance:
+                  - |-
+                    Carry an existing `name` through every edit — it is the user's label
+                    for the tab, and an entry sent without it loses the label. Duplicate
+                    names across entries are allowed. Set one only when the user names
+                    the source object; never invent labels.
+                examples:
+                  - Billing address
+                  - Shipping address
               sourceDataType:
                 type: string
                 description: |
@@ -1158,17 +1181,31 @@ components:
                 type: object
                 description: |
                   Defines conditional rules for including each array element in the result.
+                x-celigo-ai-guidance:
+                  - |-
+                    Judged against this entry's own `extract` (the array source). The
+                    design scopes the UI's tab-level "Action to take if source field has
+                    no value" to copy-as-is tabs (no child `mappings`); the API accepts
+                    `fail_record_when_empty` on a mapped entry as well, and the mapper
+                    processor honors it there — the record fails when that array is
+                    missing or empty (`errors[]` entry `code: extract_empty`, `fatal:
+                    true`, message `<generate>: Source field has no value`; probed
+                    2026-10-09). Say so when writing it on a mapped entry: the user may
+                    not find the setting in the mapper's tab. To fail on an empty field
+                    inside each element, set the action on that child mapping instead.
                 properties:
                   when:
                     type: string
                     description: |
-                      Specifies the condition that must be met for an array element to be included.
-
-                      'extract_not_empty' only includes elements where the extract field returns a value.
+                      Condition judged on the entry's extract — skip the elements the
+                      extract does not return, or fail the whole record when the source
+                      array is missing or empty.
                     enum:
                       - extract_not_empty
+                      - fail_record_when_empty
                     x-enumDescriptions:
-                      extract_not_empty: Include the array element only when the extract field returns a non-empty value.
+                      extract_not_empty: Include an array element only when the extract returns a non-empty value for it
+                      fail_record_when_empty: Fail the record when the entry's source array is missing or empty
                     examples:
                       - extract_not_empty
               mappings:
@@ -1268,6 +1305,20 @@ components:
                       extract: $.price
                       dataType: number
                       status: Active
+            if:
+              properties:
+                conditional:
+                  properties:
+                    when:
+                      const: fail_record_when_empty
+                  required:
+                    - when
+              required:
+                - conditional
+            then:
+              not:
+                required:
+                  - default
         status:
           type: string
           description: |
@@ -1275,9 +1326,10 @@ components:
             Required on every mapping entry. Controls whether the mapping is applied.
 
             **Guidance**
-            Emit `"Active"` for mappings that should run; `"Draft"` saves an
-            in-progress mapping without the Active-only field validations. The
-            API rejects a mapping missing this field
+            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.").
           x-celigo-ai-guidance:
             - |-
@@ -1286,12 +1338,28 @@ components:
               field validations. The value is case-sensitive. The API rejects:
               - Missing field: `[status_field_absent] Mapping object must have status field present.`
               - Wrong case (e.g. `"active"`): `[invalid_status_enums] active is not a valid enum for status field.`
+            - |-
+              `"Inactive"` is the user's "Set inactive" on a row: use it only when
+              asked to disable or park a row, never to mean incomplete (that is
+              `"Draft"`). Setting a parent `Inactive` means no `Active` row may
+              remain under it — the save rejects an `Active` row under an
+              `Inactive` parent (`[inactive_parent_active_child]` on `mappings`,
+              no message text) and never cascades or promotes on its own; `Draft`
+              descendants are kept as they are, and a `Draft` parent does not gate
+              its children. The UI's Set inactive on a parent marks the parent and
+              every child `Inactive` (IO-166197). Re-enabling a child
+              means re-enabling its ancestors in the same payload. Edits that keep
+              existing rows must carry their stored status forward — rewriting a
+              `Draft` or `Inactive` row to `Active` turns a row the user parked
+              back on.
           enum:
             - Active
             - Draft
+            - Inactive
           x-enumDescriptions:
-            Active: The mapping is enabled and applied during processing.
-            Draft: In-progress mapping; saved without the Active-only field validations.
+            Active: The mapping is enabled and applied during processing
+            Draft: In-progress mapping; saved without the Active-only field validations and skipped at runtime
+            Inactive: Disabled by the user; configuration kept, skipped at runtime and in preview
           examples:
             - Active
         conditional:
@@ -1320,6 +1388,10 @@ components:
             - `extract_not_empty`: Apply only when the extract field returns a value
               Useful for conditional mapping based on input data availability
 
+            - `fail_record_when_empty`: Fail the record when the extract field returns
+              no value (the UI's "Cause record to fail" action when the source field
+              has no value)
+
             **Example**
             ```json
             {
@@ -1332,28 +1404,75 @@ components:
               }
             }
             ```
+          x-celigo-ai-guidance:
+            - |-
+              `when` holds one value, and two different settings share it: the
+              composite-import operation gate (`record_created` / `record_updated`,
+              the UI's "Only perform mapping when") and the empty-source action
+              (`extract_not_empty` / `fail_record_when_empty`, the UI's "Action to
+              take if source field has no value"). A row cannot carry both — writing
+              one replaces the other and the save succeeds, so a composite import
+              row that needs both has to choose. Never author `fail_record_when_empty`
+              on a row that already carries `record_created` or `record_updated`.
           properties:
             when:
               type: string
               description: |
-                Specifies the condition that triggers application of this mapping:
-                - record_created: Apply only when creating a new record
-                - record_updated: Apply only when updating an existing record
-                - extract_not_empty: Apply only when the extract field returns a value
+                Condition that gates this mapping — either an operation gate on a
+                composite (create-or-update) import or the action to take when the
+                extract returns no value. Empty means null, undefined or an empty
+                string; `0`, `false` and whitespace are values.
+              x-celigo-ai-guidance:
+                - |-
+                  `fail_record_when_empty` is the fourth "Action to take if source field
+                  has no value" and is mutually exclusive with the other three: send it
+                  with no `default` key. A `default`, a `lookupName` or a `hardCodedValue`
+                  on the same row — or a `default` on a `buildArrayHelper` entry — is
+                  rejected at save with `[unsupported_mapping] "<key>" and conditional.when
+                  "fail_record_when_empty" cannot be present in mapping simultaneously.`
+                  (the lookup variant adds `Use lookup "allowFailures" instead.`);
+                  lookups fail through `allowFailures: false`, and a hard-coded row
+                  always has a value. At runtime an empty extract fails the record with
+                  an `errors[]` entry `{code: "extract_empty", fatal: true, source:
+                  "mapping", message: "<generate>: Source field has no value"}`
+                  ("Input field has no value" in a Transformation 2.0); `0` and `false`
+                  are values and map through.
               enum:
                 - record_created
                 - record_updated
                 - extract_not_empty
+                - fail_record_when_empty
               x-enumDescriptions:
-                record_created: Apply this mapping only when creating a new record.
-                record_updated: Apply this mapping only when updating an existing record.
-                extract_not_empty: Apply this mapping only when the extract field returns a non-empty value.
+                record_created: Apply this mapping only when creating a new record
+                record_updated: Apply this mapping only when updating an existing record
+                extract_not_empty: Apply this mapping only when the extract field returns a non-empty value
+                fail_record_when_empty: Fail the record when the extract field returns no value
               examples:
                 - record_created
                 - record_updated
                 - extract_not_empty
+                - fail_record_when_empty
       required:
         - dataType
+      if:
+        properties:
+          conditional:
+            properties:
+              when:
+                const: fail_record_when_empty
+            required:
+              - when
+        required:
+          - conditional
+      then:
+        not:
+          anyOf:
+            - required:
+                - default
+            - required:
+                - lookupName
+            - required:
+                - hardCodedValue
     Mappings:
       type: array
       description: |
@@ -1377,6 +1496,20 @@ components:
 
         The system will process these nested structures recursively during runtime, ensuring proper construction
         of complex hierarchical data while maintaining excellent performance.
+
+        On save, a leaf row with neither a source (`extract`, `hardCodedValue`, `lookupName`) nor a
+        destination (`generate`) is dropped silently, at every nesting level, and so is an object or
+        object-array row left with no source, no destination and no remaining child `mappings` or
+        `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
+        wrapper that still has children, are kept.
+      x-celigo-ai-guidance:
+        - |-
+          Rows that exist in the saved document — including `Draft` and `Inactive` rows and
+          rows with only a source or only a destination — are the user's state: an edit that
+          re-sends the tree must carry them through unchanged unless the user asked to change
+          them. Only a row with neither source nor destination — and, for an object or
+          object-array row, no remaining children — can be left out; the save would drop it
+          anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
       items:
         type: object
         properties:
@@ -1656,7 +1789,8 @@ components:
               Explicit JSON `null` is itself a valid fallback: the destination field is written as
               JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
               action). Omitting the key entirely means no fallback — the field is left out of the
-              output when the extract is empty (the UI's "Do nothing" action).
+              output when the extract is empty (the UI's "Do nothing" action). Failing the record
+              instead is `conditional.when: fail_record_when_empty`, which excludes a default.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
@@ -1665,6 +1799,12 @@ components:
                 Preserve them verbatim when editing or migrating a mapping — dropping
                 the key changes runtime behavior from "use null/empty string as
                 default value" to "do nothing" (field omitted from the output).
+              - |-
+                The four "Action to take if source field has no value" choices map to:
+                do nothing → no `default` key (optionally `conditional.when:
+                extract_not_empty`); use null → `"default": null`; use empty string or
+                a custom value → `"default": "<value>"`; cause the record to fail →
+                `conditional.when: fail_record_when_empty` with no `default` key.
             examples:
               - N/A
               - '0'
@@ -1997,6 +2137,22 @@ components:
                     - $.order.lineItems[*]
                     - $.parents[*].children[*]
                     - $
+                name:
+                  type: string
+                  maxLength: 200
+                  description: |
+                    Display label for this source object in the mapper, so the sources of
+                    an object array can be told apart instead of all showing as `$`.
+                    Has no effect at runtime; stored only when non-empty.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Carry an existing `name` through every edit — it is the user's label
+                      for the tab, and an entry sent without it loses the label. Duplicate
+                      names across entries are allowed. Set one only when the user names
+                      the source object; never invent labels.
+                  examples:
+                    - Billing address
+                    - Shipping address
                 sourceDataType:
                   type: string
                   description: |
@@ -2045,17 +2201,31 @@ components:
                   type: object
                   description: |
                     Defines conditional rules for including each array element in the result.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Judged against this entry's own `extract` (the array source). The
+                      design scopes the UI's tab-level "Action to take if source field has
+                      no value" to copy-as-is tabs (no child `mappings`); the API accepts
+                      `fail_record_when_empty` on a mapped entry as well, and the mapper
+                      processor honors it there — the record fails when that array is
+                      missing or empty (`errors[]` entry `code: extract_empty`, `fatal:
+                      true`, message `<generate>: Source field has no value`; probed
+                      2026-10-09). Say so when writing it on a mapped entry: the user may
+                      not find the setting in the mapper's tab. To fail on an empty field
+                      inside each element, set the action on that child mapping instead.
                   properties:
                     when:
                       type: string
                       description: |
-                        Specifies the condition that must be met for an array element to be included.
-
-                        'extract_not_empty' only includes elements where the extract field returns a value.
+                        Condition judged on the entry's extract — skip the elements the
+                        extract does not return, or fail the whole record when the source
+                        array is missing or empty.
                       enum:
                         - extract_not_empty
+                        - fail_record_when_empty
                       x-enumDescriptions:
-                        extract_not_empty: Include the array element only when the extract field returns a non-empty value.
+                        extract_not_empty: Include an array element only when the extract returns a non-empty value for it
+                        fail_record_when_empty: Fail the record when the entry's source array is missing or empty
                       examples:
                         - extract_not_empty
                 mappings:
@@ -2155,6 +2325,20 @@ components:
                         extract: $.price
                         dataType: number
                         status: Active
+              if:
+                properties:
+                  conditional:
+                    properties:
+                      when:
+                        const: fail_record_when_empty
+                    required:
+                      - when
+                required:
+                  - conditional
+              then:
+                not:
+                  required:
+                    - default
           status:
             type: string
             description: |
@@ -2162,9 +2346,10 @@ components:
               Required on every mapping entry. Controls whether the mapping is applied.
 
               **Guidance**
-              Emit `"Active"` for mappings that should run; `"Draft"` saves an
-              in-progress mapping without the Active-only field validations. The
-              API rejects a mapping missing this field
+              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.").
             x-celigo-ai-guidance:
               - |-
@@ -2173,12 +2358,28 @@ components:
                 field validations. The value is case-sensitive. The API rejects:
                 - Missing field: `[status_field_absent] Mapping object must have status field present.`
                 - Wrong case (e.g. `"active"`): `[invalid_status_enums] active is not a valid enum for status field.`
+              - |-
+                `"Inactive"` is the user's "Set inactive" on a row: use it only when
+                asked to disable or park a row, never to mean incomplete (that is
+                `"Draft"`). Setting a parent `Inactive` means no `Active` row may
+                remain under it — the save rejects an `Active` row under an
+                `Inactive` parent (`[inactive_parent_active_child]` on `mappings`,
+                no message text) and never cascades or promotes on its own; `Draft`
+                descendants are kept as they are, and a `Draft` parent does not gate
+                its children. The UI's Set inactive on a parent marks the parent and
+                every child `Inactive` (IO-166197). Re-enabling a child
+                means re-enabling its ancestors in the same payload. Edits that keep
+                existing rows must carry their stored status forward — rewriting a
+                `Draft` or `Inactive` row to `Active` turns a row the user parked
+                back on.
             enum:
               - Active
               - Draft
+              - Inactive
             x-enumDescriptions:
-              Active: The mapping is enabled and applied during processing.
-              Draft: In-progress mapping; saved without the Active-only field validations.
+              Active: The mapping is enabled and applied during processing
+              Draft: In-progress mapping; saved without the Active-only field validations and skipped at runtime
+              Inactive: Disabled by the user; configuration kept, skipped at runtime and in preview
             examples:
               - Active
           conditional:
@@ -2207,6 +2408,10 @@ components:
               - `extract_not_empty`: Apply only when the extract field returns a value
                 Useful for conditional mapping based on input data availability
 
+              - `fail_record_when_empty`: Fail the record when the extract field returns
+                no value (the UI's "Cause record to fail" action when the source field
+                has no value)
+
               **Example**
               ```json
               {
@@ -2219,28 +2424,75 @@ components:
                 }
               }
               ```
+            x-celigo-ai-guidance:
+              - |-
+                `when` holds one value, and two different settings share it: the
+                composite-import operation gate (`record_created` / `record_updated`,
+                the UI's "Only perform mapping when") and the empty-source action
+                (`extract_not_empty` / `fail_record_when_empty`, the UI's "Action to
+                take if source field has no value"). A row cannot carry both — writing
+                one replaces the other and the save succeeds, so a composite import
+                row that needs both has to choose. Never author `fail_record_when_empty`
+                on a row that already carries `record_created` or `record_updated`.
             properties:
               when:
                 type: string
                 description: |
-                  Specifies the condition that triggers application of this mapping:
-                  - record_created: Apply only when creating a new record
-                  - record_updated: Apply only when updating an existing record
-                  - extract_not_empty: Apply only when the extract field returns a value
+                  Condition that gates this mapping — either an operation gate on a
+                  composite (create-or-update) import or the action to take when the
+                  extract returns no value. Empty means null, undefined or an empty
+                  string; `0`, `false` and whitespace are values.
+                x-celigo-ai-guidance:
+                  - |-
+                    `fail_record_when_empty` is the fourth "Action to take if source field
+                    has no value" and is mutually exclusive with the other three: send it
+                    with no `default` key. A `default`, a `lookupName` or a `hardCodedValue`
+                    on the same row — or a `default` on a `buildArrayHelper` entry — is
+                    rejected at save with `[unsupported_mapping] "<key>" and conditional.when
+                    "fail_record_when_empty" cannot be present in mapping simultaneously.`
+                    (the lookup variant adds `Use lookup "allowFailures" instead.`);
+                    lookups fail through `allowFailures: false`, and a hard-coded row
+                    always has a value. At runtime an empty extract fails the record with
+                    an `errors[]` entry `{code: "extract_empty", fatal: true, source:
+                    "mapping", message: "<generate>: Source field has no value"}`
+                    ("Input field has no value" in a Transformation 2.0); `0` and `false`
+                    are values and map through.
                 enum:
                   - record_created
                   - record_updated
                   - extract_not_empty
+                  - fail_record_when_empty
                 x-enumDescriptions:
-                  record_created: Apply this mapping only when creating a new record.
-                  record_updated: Apply this mapping only when updating an existing record.
-                  extract_not_empty: Apply this mapping only when the extract field returns a non-empty value.
+                  record_created: Apply this mapping only when creating a new record
+                  record_updated: Apply this mapping only when updating an existing record
+                  extract_not_empty: Apply this mapping only when the extract field returns a non-empty value
+                  fail_record_when_empty: Fail the record when the extract field returns no value
                 examples:
                   - record_created
                   - record_updated
                   - extract_not_empty
+                  - fail_record_when_empty
         required:
           - dataType
+        if:
+          properties:
+            conditional:
+              properties:
+                when:
+                  const: fail_record_when_empty
+              required:
+                - when
+          required:
+            - conditional
+        then:
+          not:
+            anyOf:
+              - required:
+                  - default
+              - required:
+                  - lookupName
+              - required:
+                  - hardCodedValue
     Lookups:
       type: array
       description: |