@celigo/api-specs 0.2.198 → 0.2.200

package/dist/ai-agent.yml

@@ -2831,28 +2831,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-            while a null source is still written as null unless `conditional.when` is
-            `extract_not_empty`. Failing the record instead is `conditional.when:
-            fail_record_when_empty`, which excludes a default.
+            action). Outside the database and csv / xlsx file imports described below, omitting the
+            key means no fallback — the field is left out of the output when the extract is missing
+            or an empty string (the UI's "Do nothing" action), while a null source is still written
+            as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+            `conditional.when: fail_record_when_empty`, which excludes a default.
+
+            On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+            import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+            records is not one), the save stores an omitted key as `null` on every row that has no
+            `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+            conditional — the same default the Mapper UI preselects for those imports. The rule runs
+            when the document is saved, on create and on update, so "Do nothing" on those imports is
+            `conditional.when: extract_not_empty`, not an omitted key.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
               absent keys: null renders the destination field as JSON null and the
               empty string renders it as `""` when the extract yields nothing.
-              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" (a missing or `""` source is left out
-              of the output, while a null source is written as null unless
-              `conditional.when` is `extract_not_empty`).
+              Preserve them verbatim when editing or migrating a mapping. Outside
+              the database / csv-xlsx file import set, dropping the key changes
+              runtime behavior from "use null/empty string as default value" to "do
+              nothing" (a missing or `""` source is left out of the output, while a
+              null source is written as null unless `conditional.when` is
+              `extract_not_empty`); inside that set the save writes a dropped key
+              back as `"default": null`, so dropping a stored null changes nothing
+              while dropping a stored `""` or any other explicit value replaces it
+              with null.
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (add `conditional.when:
-              extract_not_empty` to leave a null source out too; without it a null
-              source is written as null); use null → `"default": null`; use empty string or
-              a custom value → `"default": "<value>"`; cause the record to fail →
+              do nothing → `conditional.when: extract_not_empty` with no `default` key
+              (on imports outside the database / csv-xlsx file set the key may simply
+              be omitted, but a null source is then still written as null); 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.
+            - |-
+              On a database or csv / xlsx file import, a row sent with neither a
+              `default` nor one of those conditionals reads back with `"default": null`
+              after the save — create or update — so the destination is written as
+              null; never express "Do nothing" by omission there. A stored
+              `"default": null` on such a row is this save-time default, not a user's
+              choice; keep it when re-sending the row. `"default": null` sent together
+              with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+              `"default" and conditional.when "fail_record_when_empty" cannot be
+              present in mapping simultaneously.`
           examples:
             - N/A
             - '0'
@@ -3259,7 +3282,10 @@ components:
                   not found in the input data.
 
                   Explicit JSON `null` is itself a valid fallback (the element is written as
-                  JSON null); omitting the key means no fallback is applied.
+                  JSON null); omitting the key means no fallback is applied — except on database
+                  and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                  entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                  does on leaf rows.
                 examples:
                   - N/A
                   - '0'
@@ -3929,28 +3955,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-              while a null source is still written as null unless `conditional.when` is
-              `extract_not_empty`. Failing the record instead is `conditional.when:
-              fail_record_when_empty`, which excludes a default.
+              action). Outside the database and csv / xlsx file imports described below, omitting the
+              key means no fallback — the field is left out of the output when the extract is missing
+              or an empty string (the UI's "Do nothing" action), while a null source is still written
+              as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+              `conditional.when: fail_record_when_empty`, which excludes a default.
+
+              On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+              import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+              records is not one), the save stores an omitted key as `null` on every row that has no
+              `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+              conditional — the same default the Mapper UI preselects for those imports. The rule runs
+              when the document is saved, on create and on update, so "Do nothing" on those imports is
+              `conditional.when: extract_not_empty`, not an omitted key.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
                 absent keys: null renders the destination field as JSON null and the
                 empty string renders it as `""` when the extract yields nothing.
-                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" (a missing or `""` source is left out
-                of the output, while a null source is written as null unless
-                `conditional.when` is `extract_not_empty`).
+                Preserve them verbatim when editing or migrating a mapping. Outside
+                the database / csv-xlsx file import set, dropping the key changes
+                runtime behavior from "use null/empty string as default value" to "do
+                nothing" (a missing or `""` source is left out of the output, while a
+                null source is written as null unless `conditional.when` is
+                `extract_not_empty`); inside that set the save writes a dropped key
+                back as `"default": null`, so dropping a stored null changes nothing
+                while dropping a stored `""` or any other explicit value replaces it
+                with null.
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (add `conditional.when:
-                extract_not_empty` to leave a null source out too; without it a null
-                source is written as null); use null → `"default": null`; use empty string or
-                a custom value → `"default": "<value>"`; cause the record to fail →
+                do nothing → `conditional.when: extract_not_empty` with no `default` key
+                (on imports outside the database / csv-xlsx file set the key may simply
+                be omitted, but a null source is then still written as null); 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.
+              - |-
+                On a database or csv / xlsx file import, a row sent with neither a
+                `default` nor one of those conditionals reads back with `"default": null`
+                after the save — create or update — so the destination is written as
+                null; never express "Do nothing" by omission there. A stored
+                `"default": null` on such a row is this save-time default, not a user's
+                choice; keep it when re-sending the row. `"default": null` sent together
+                with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+                `"default" and conditional.when "fail_record_when_empty" cannot be
+                present in mapping simultaneously.`
             examples:
               - N/A
               - '0'
@@ -4357,7 +4406,10 @@ components:
                     not found in the input data.
 
                     Explicit JSON `null` is itself a valid fallback (the element is written as
-                    JSON null); omitting the key means no fallback is applied.
+                    JSON null); omitting the key means no fallback is applied — except on database
+                    and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                    entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                    does on leaf rows.
                   examples:
                     - N/A
                     - '0'

package/dist/api.yml

@@ -2909,28 +2909,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-            while a null source is still written as null unless `conditional.when` is
-            `extract_not_empty`. Failing the record instead is `conditional.when:
-            fail_record_when_empty`, which excludes a default.
+            action). Outside the database and csv / xlsx file imports described below, omitting the
+            key means no fallback — the field is left out of the output when the extract is missing
+            or an empty string (the UI's "Do nothing" action), while a null source is still written
+            as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+            `conditional.when: fail_record_when_empty`, which excludes a default.
+
+            On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+            import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+            records is not one), the save stores an omitted key as `null` on every row that has no
+            `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+            conditional — the same default the Mapper UI preselects for those imports. The rule runs
+            when the document is saved, on create and on update, so "Do nothing" on those imports is
+            `conditional.when: extract_not_empty`, not an omitted key.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
               absent keys: null renders the destination field as JSON null and the
               empty string renders it as `""` when the extract yields nothing.
-              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" (a missing or `""` source is left out
-              of the output, while a null source is written as null unless
-              `conditional.when` is `extract_not_empty`).
+              Preserve them verbatim when editing or migrating a mapping. Outside
+              the database / csv-xlsx file import set, dropping the key changes
+              runtime behavior from "use null/empty string as default value" to "do
+              nothing" (a missing or `""` source is left out of the output, while a
+              null source is written as null unless `conditional.when` is
+              `extract_not_empty`); inside that set the save writes a dropped key
+              back as `"default": null`, so dropping a stored null changes nothing
+              while dropping a stored `""` or any other explicit value replaces it
+              with null.
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (add `conditional.when:
-              extract_not_empty` to leave a null source out too; without it a null
-              source is written as null); use null → `"default": null`; use empty string or
-              a custom value → `"default": "<value>"`; cause the record to fail →
+              do nothing → `conditional.when: extract_not_empty` with no `default` key
+              (on imports outside the database / csv-xlsx file set the key may simply
+              be omitted, but a null source is then still written as null); 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.
+            - |-
+              On a database or csv / xlsx file import, a row sent with neither a
+              `default` nor one of those conditionals reads back with `"default": null`
+              after the save — create or update — so the destination is written as
+              null; never express "Do nothing" by omission there. A stored
+              `"default": null` on such a row is this save-time default, not a user's
+              choice; keep it when re-sending the row. `"default": null` sent together
+              with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+              `"default" and conditional.when "fail_record_when_empty" cannot be
+              present in mapping simultaneously.`
           examples:
             - N/A
             - '0'
@@ -3337,7 +3360,10 @@ components:
                   not found in the input data.
 
                   Explicit JSON `null` is itself a valid fallback (the element is written as
-                  JSON null); omitting the key means no fallback is applied.
+                  JSON null); omitting the key means no fallback is applied — except on database
+                  and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                  entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                  does on leaf rows.
                 examples:
                   - N/A
                   - '0'
@@ -4007,28 +4033,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-              while a null source is still written as null unless `conditional.when` is
-              `extract_not_empty`. Failing the record instead is `conditional.when:
-              fail_record_when_empty`, which excludes a default.
+              action). Outside the database and csv / xlsx file imports described below, omitting the
+              key means no fallback — the field is left out of the output when the extract is missing
+              or an empty string (the UI's "Do nothing" action), while a null source is still written
+              as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+              `conditional.when: fail_record_when_empty`, which excludes a default.
+
+              On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+              import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+              records is not one), the save stores an omitted key as `null` on every row that has no
+              `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+              conditional — the same default the Mapper UI preselects for those imports. The rule runs
+              when the document is saved, on create and on update, so "Do nothing" on those imports is
+              `conditional.when: extract_not_empty`, not an omitted key.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
                 absent keys: null renders the destination field as JSON null and the
                 empty string renders it as `""` when the extract yields nothing.
-                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" (a missing or `""` source is left out
-                of the output, while a null source is written as null unless
-                `conditional.when` is `extract_not_empty`).
+                Preserve them verbatim when editing or migrating a mapping. Outside
+                the database / csv-xlsx file import set, dropping the key changes
+                runtime behavior from "use null/empty string as default value" to "do
+                nothing" (a missing or `""` source is left out of the output, while a
+                null source is written as null unless `conditional.when` is
+                `extract_not_empty`); inside that set the save writes a dropped key
+                back as `"default": null`, so dropping a stored null changes nothing
+                while dropping a stored `""` or any other explicit value replaces it
+                with null.
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (add `conditional.when:
-                extract_not_empty` to leave a null source out too; without it a null
-                source is written as null); use null → `"default": null`; use empty string or
-                a custom value → `"default": "<value>"`; cause the record to fail →
+                do nothing → `conditional.when: extract_not_empty` with no `default` key
+                (on imports outside the database / csv-xlsx file set the key may simply
+                be omitted, but a null source is then still written as null); 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.
+              - |-
+                On a database or csv / xlsx file import, a row sent with neither a
+                `default` nor one of those conditionals reads back with `"default": null`
+                after the save — create or update — so the destination is written as
+                null; never express "Do nothing" by omission there. A stored
+                `"default": null` on such a row is this save-time default, not a user's
+                choice; keep it when re-sending the row. `"default": null` sent together
+                with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+                `"default" and conditional.when "fail_record_when_empty" cannot be
+                present in mapping simultaneously.`
             examples:
               - N/A
               - '0'
@@ -4435,7 +4484,10 @@ components:
                     not found in the input data.
 
                     Explicit JSON `null` is itself a valid fallback (the element is written as
-                    JSON null); omitting the key means no fallback is applied.
+                    JSON null); omitting the key means no fallback is applied — except on database
+                    and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                    entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                    does on leaf rows.
                   examples:
                     - N/A
                     - '0'

package/dist/asynchelper.yml

@@ -805,28 +805,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-            while a null source is still written as null unless `conditional.when` is
-            `extract_not_empty`. Failing the record instead is `conditional.when:
-            fail_record_when_empty`, which excludes a default.
+            action). Outside the database and csv / xlsx file imports described below, omitting the
+            key means no fallback — the field is left out of the output when the extract is missing
+            or an empty string (the UI's "Do nothing" action), while a null source is still written
+            as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+            `conditional.when: fail_record_when_empty`, which excludes a default.
+
+            On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+            import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+            records is not one), the save stores an omitted key as `null` on every row that has no
+            `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+            conditional — the same default the Mapper UI preselects for those imports. The rule runs
+            when the document is saved, on create and on update, so "Do nothing" on those imports is
+            `conditional.when: extract_not_empty`, not an omitted key.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
               absent keys: null renders the destination field as JSON null and the
               empty string renders it as `""` when the extract yields nothing.
-              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" (a missing or `""` source is left out
-              of the output, while a null source is written as null unless
-              `conditional.when` is `extract_not_empty`).
+              Preserve them verbatim when editing or migrating a mapping. Outside
+              the database / csv-xlsx file import set, dropping the key changes
+              runtime behavior from "use null/empty string as default value" to "do
+              nothing" (a missing or `""` source is left out of the output, while a
+              null source is written as null unless `conditional.when` is
+              `extract_not_empty`); inside that set the save writes a dropped key
+              back as `"default": null`, so dropping a stored null changes nothing
+              while dropping a stored `""` or any other explicit value replaces it
+              with null.
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (add `conditional.when:
-              extract_not_empty` to leave a null source out too; without it a null
-              source is written as null); use null → `"default": null`; use empty string or
-              a custom value → `"default": "<value>"`; cause the record to fail →
+              do nothing → `conditional.when: extract_not_empty` with no `default` key
+              (on imports outside the database / csv-xlsx file set the key may simply
+              be omitted, but a null source is then still written as null); 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.
+            - |-
+              On a database or csv / xlsx file import, a row sent with neither a
+              `default` nor one of those conditionals reads back with `"default": null`
+              after the save — create or update — so the destination is written as
+              null; never express "Do nothing" by omission there. A stored
+              `"default": null` on such a row is this save-time default, not a user's
+              choice; keep it when re-sending the row. `"default": null` sent together
+              with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+              `"default" and conditional.when "fail_record_when_empty" cannot be
+              present in mapping simultaneously.`
           examples:
             - N/A
             - '0'
@@ -1233,7 +1256,10 @@ components:
                   not found in the input data.
 
                   Explicit JSON `null` is itself a valid fallback (the element is written as
-                  JSON null); omitting the key means no fallback is applied.
+                  JSON null); omitting the key means no fallback is applied — except on database
+                  and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                  entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                  does on leaf rows.
                 examples:
                   - N/A
                   - '0'
@@ -1903,28 +1929,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-              while a null source is still written as null unless `conditional.when` is
-              `extract_not_empty`. Failing the record instead is `conditional.when:
-              fail_record_when_empty`, which excludes a default.
+              action). Outside the database and csv / xlsx file imports described below, omitting the
+              key means no fallback — the field is left out of the output when the extract is missing
+              or an empty string (the UI's "Do nothing" action), while a null source is still written
+              as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+              `conditional.when: fail_record_when_empty`, which excludes a default.
+
+              On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+              import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+              records is not one), the save stores an omitted key as `null` on every row that has no
+              `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+              conditional — the same default the Mapper UI preselects for those imports. The rule runs
+              when the document is saved, on create and on update, so "Do nothing" on those imports is
+              `conditional.when: extract_not_empty`, not an omitted key.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
                 absent keys: null renders the destination field as JSON null and the
                 empty string renders it as `""` when the extract yields nothing.
-                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" (a missing or `""` source is left out
-                of the output, while a null source is written as null unless
-                `conditional.when` is `extract_not_empty`).
+                Preserve them verbatim when editing or migrating a mapping. Outside
+                the database / csv-xlsx file import set, dropping the key changes
+                runtime behavior from "use null/empty string as default value" to "do
+                nothing" (a missing or `""` source is left out of the output, while a
+                null source is written as null unless `conditional.when` is
+                `extract_not_empty`); inside that set the save writes a dropped key
+                back as `"default": null`, so dropping a stored null changes nothing
+                while dropping a stored `""` or any other explicit value replaces it
+                with null.
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (add `conditional.when:
-                extract_not_empty` to leave a null source out too; without it a null
-                source is written as null); use null → `"default": null`; use empty string or
-                a custom value → `"default": "<value>"`; cause the record to fail →
+                do nothing → `conditional.when: extract_not_empty` with no `default` key
+                (on imports outside the database / csv-xlsx file set the key may simply
+                be omitted, but a null source is then still written as null); 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.
+              - |-
+                On a database or csv / xlsx file import, a row sent with neither a
+                `default` nor one of those conditionals reads back with `"default": null`
+                after the save — create or update — so the destination is written as
+                null; never express "Do nothing" by omission there. A stored
+                `"default": null` on such a row is this save-time default, not a user's
+                choice; keep it when re-sending the row. `"default": null` sent together
+                with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+                `"default" and conditional.when "fail_record_when_empty" cannot be
+                present in mapping simultaneously.`
             examples:
               - N/A
               - '0'
@@ -2331,7 +2380,10 @@ components:
                     not found in the input data.
 
                     Explicit JSON `null` is itself a valid fallback (the element is written as
-                    JSON null); omitting the key means no fallback is applied.
+                    JSON null); omitting the key means no fallback is applied — except on database
+                    and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                    entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                    does on leaf rows.
                   examples:
                     - N/A
                     - '0'

package/dist/export.yml

@@ -12979,28 +12979,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-            while a null source is still written as null unless `conditional.when` is
-            `extract_not_empty`. Failing the record instead is `conditional.when:
-            fail_record_when_empty`, which excludes a default.
+            action). Outside the database and csv / xlsx file imports described below, omitting the
+            key means no fallback — the field is left out of the output when the extract is missing
+            or an empty string (the UI's "Do nothing" action), while a null source is still written
+            as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+            `conditional.when: fail_record_when_empty`, which excludes a default.
+
+            On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+            import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+            records is not one), the save stores an omitted key as `null` on every row that has no
+            `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+            conditional — the same default the Mapper UI preselects for those imports. The rule runs
+            when the document is saved, on create and on update, so "Do nothing" on those imports is
+            `conditional.when: extract_not_empty`, not an omitted key.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
               absent keys: null renders the destination field as JSON null and the
               empty string renders it as `""` when the extract yields nothing.
-              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" (a missing or `""` source is left out
-              of the output, while a null source is written as null unless
-              `conditional.when` is `extract_not_empty`).
+              Preserve them verbatim when editing or migrating a mapping. Outside
+              the database / csv-xlsx file import set, dropping the key changes
+              runtime behavior from "use null/empty string as default value" to "do
+              nothing" (a missing or `""` source is left out of the output, while a
+              null source is written as null unless `conditional.when` is
+              `extract_not_empty`); inside that set the save writes a dropped key
+              back as `"default": null`, so dropping a stored null changes nothing
+              while dropping a stored `""` or any other explicit value replaces it
+              with null.
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (add `conditional.when:
-              extract_not_empty` to leave a null source out too; without it a null
-              source is written as null); use null → `"default": null`; use empty string or
-              a custom value → `"default": "<value>"`; cause the record to fail →
+              do nothing → `conditional.when: extract_not_empty` with no `default` key
+              (on imports outside the database / csv-xlsx file set the key may simply
+              be omitted, but a null source is then still written as null); 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.
+            - |-
+              On a database or csv / xlsx file import, a row sent with neither a
+              `default` nor one of those conditionals reads back with `"default": null`
+              after the save — create or update — so the destination is written as
+              null; never express "Do nothing" by omission there. A stored
+              `"default": null` on such a row is this save-time default, not a user's
+              choice; keep it when re-sending the row. `"default": null` sent together
+              with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+              `"default" and conditional.when "fail_record_when_empty" cannot be
+              present in mapping simultaneously.`
           examples:
             - N/A
             - '0'
@@ -13407,7 +13430,10 @@ components:
                   not found in the input data.
 
                   Explicit JSON `null` is itself a valid fallback (the element is written as
-                  JSON null); omitting the key means no fallback is applied.
+                  JSON null); omitting the key means no fallback is applied — except on database
+                  and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                  entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                  does on leaf rows.
                 examples:
                   - N/A
                   - '0'
@@ -14077,28 +14103,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-              while a null source is still written as null unless `conditional.when` is
-              `extract_not_empty`. Failing the record instead is `conditional.when:
-              fail_record_when_empty`, which excludes a default.
+              action). Outside the database and csv / xlsx file imports described below, omitting the
+              key means no fallback — the field is left out of the output when the extract is missing
+              or an empty string (the UI's "Do nothing" action), while a null source is still written
+              as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+              `conditional.when: fail_record_when_empty`, which excludes a default.
+
+              On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+              import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+              records is not one), the save stores an omitted key as `null` on every row that has no
+              `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+              conditional — the same default the Mapper UI preselects for those imports. The rule runs
+              when the document is saved, on create and on update, so "Do nothing" on those imports is
+              `conditional.when: extract_not_empty`, not an omitted key.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
                 absent keys: null renders the destination field as JSON null and the
                 empty string renders it as `""` when the extract yields nothing.
-                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" (a missing or `""` source is left out
-                of the output, while a null source is written as null unless
-                `conditional.when` is `extract_not_empty`).
+                Preserve them verbatim when editing or migrating a mapping. Outside
+                the database / csv-xlsx file import set, dropping the key changes
+                runtime behavior from "use null/empty string as default value" to "do
+                nothing" (a missing or `""` source is left out of the output, while a
+                null source is written as null unless `conditional.when` is
+                `extract_not_empty`); inside that set the save writes a dropped key
+                back as `"default": null`, so dropping a stored null changes nothing
+                while dropping a stored `""` or any other explicit value replaces it
+                with null.
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (add `conditional.when:
-                extract_not_empty` to leave a null source out too; without it a null
-                source is written as null); use null → `"default": null`; use empty string or
-                a custom value → `"default": "<value>"`; cause the record to fail →
+                do nothing → `conditional.when: extract_not_empty` with no `default` key
+                (on imports outside the database / csv-xlsx file set the key may simply
+                be omitted, but a null source is then still written as null); 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.
+              - |-
+                On a database or csv / xlsx file import, a row sent with neither a
+                `default` nor one of those conditionals reads back with `"default": null`
+                after the save — create or update — so the destination is written as
+                null; never express "Do nothing" by omission there. A stored
+                `"default": null` on such a row is this save-time default, not a user's
+                choice; keep it when re-sending the row. `"default": null` sent together
+                with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+                `"default" and conditional.when "fail_record_when_empty" cannot be
+                present in mapping simultaneously.`
             examples:
               - N/A
               - '0'
@@ -14505,7 +14554,10 @@ components:
                     not found in the input data.
 
                     Explicit JSON `null` is itself a valid fallback (the element is written as
-                    JSON null); omitting the key means no fallback is applied.
+                    JSON null); omitting the key means no fallback is applied — except on database
+                    and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                    entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                    does on leaf rows.
                   examples:
                     - N/A
                     - '0'

package/dist/import.yml

@@ -4160,10 +4160,17 @@ components:
                       - string
                       - 'null'
                     description: |
-                      Path in the source record to extract the value from.
-                      Use dot notation for nested fields (e.g., "address.city").
-                      The platform stores `null` here on fields driven by
-                      `hardCodedValue` instead of an extract path.
+                      Path in the source record to extract the value from, in
+                      dot notation for nested fields (e.g., "address.city").
+                      A bare string is always read as a path, never as a
+                      constant — a path that matches no field sets the
+                      destination field to an empty string (""), written,
+                      not omitted and not the path text, and `discardIfEmpty`
+                      is what skips it; constants belong in `hardCodedValue`,
+                      and the platform stores `null` here on fields driven by
+                      it. A Handlebars template (contains `{{`) reads the
+                      record's fields by bare name; `{{record.<field>}}`
+                      renders an empty string, not the value.
                     examples:
                       - address.city
                   generate:
@@ -4410,9 +4417,14 @@ components:
                             Path from the source record root that produces
                             the value for this sublist column. Paths are
                             always anchored at the source record root —
-                            never relative to a pre-iterated row. The
+                            never relative to a pre-iterated row — and a
+                            bare string is always read as a path, never as a
+                            constant: a path that matches no field leaves the
+                            column absent from every line (unlike a body
+                            field, which is set to ""), never the text
+                            itself. Constants belong in `hardCodedValue`; the
                             platform stores `null` here on fields driven by
-                            `hardCodedValue` instead of an extract path.
+                            it.
                           x-celigo-ai-guidance:
                             - |-
                               Two extract patterns, often mixed in the same
@@ -13177,28 +13189,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-            while a null source is still written as null unless `conditional.when` is
-            `extract_not_empty`. Failing the record instead is `conditional.when:
-            fail_record_when_empty`, which excludes a default.
+            action). Outside the database and csv / xlsx file imports described below, omitting the
+            key means no fallback — the field is left out of the output when the extract is missing
+            or an empty string (the UI's "Do nothing" action), while a null source is still written
+            as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+            `conditional.when: fail_record_when_empty`, which excludes a default.
+
+            On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+            import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+            records is not one), the save stores an omitted key as `null` on every row that has no
+            `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+            conditional — the same default the Mapper UI preselects for those imports. The rule runs
+            when the document is saved, on create and on update, so "Do nothing" on those imports is
+            `conditional.when: extract_not_empty`, not an omitted key.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
               absent keys: null renders the destination field as JSON null and the
               empty string renders it as `""` when the extract yields nothing.
-              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" (a missing or `""` source is left out
-              of the output, while a null source is written as null unless
-              `conditional.when` is `extract_not_empty`).
+              Preserve them verbatim when editing or migrating a mapping. Outside
+              the database / csv-xlsx file import set, dropping the key changes
+              runtime behavior from "use null/empty string as default value" to "do
+              nothing" (a missing or `""` source is left out of the output, while a
+              null source is written as null unless `conditional.when` is
+              `extract_not_empty`); inside that set the save writes a dropped key
+              back as `"default": null`, so dropping a stored null changes nothing
+              while dropping a stored `""` or any other explicit value replaces it
+              with null.
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (add `conditional.when:
-              extract_not_empty` to leave a null source out too; without it a null
-              source is written as null); use null → `"default": null`; use empty string or
-              a custom value → `"default": "<value>"`; cause the record to fail →
+              do nothing → `conditional.when: extract_not_empty` with no `default` key
+              (on imports outside the database / csv-xlsx file set the key may simply
+              be omitted, but a null source is then still written as null); 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.
+            - |-
+              On a database or csv / xlsx file import, a row sent with neither a
+              `default` nor one of those conditionals reads back with `"default": null`
+              after the save — create or update — so the destination is written as
+              null; never express "Do nothing" by omission there. A stored
+              `"default": null` on such a row is this save-time default, not a user's
+              choice; keep it when re-sending the row. `"default": null` sent together
+              with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+              `"default" and conditional.when "fail_record_when_empty" cannot be
+              present in mapping simultaneously.`
           examples:
             - N/A
             - '0'
@@ -13605,7 +13640,10 @@ components:
                   not found in the input data.
 
                   Explicit JSON `null` is itself a valid fallback (the element is written as
-                  JSON null); omitting the key means no fallback is applied.
+                  JSON null); omitting the key means no fallback is applied — except on database
+                  and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                  entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                  does on leaf rows.
                 examples:
                   - N/A
                   - '0'
@@ -14275,28 +14313,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-              while a null source is still written as null unless `conditional.when` is
-              `extract_not_empty`. Failing the record instead is `conditional.when:
-              fail_record_when_empty`, which excludes a default.
+              action). Outside the database and csv / xlsx file imports described below, omitting the
+              key means no fallback — the field is left out of the output when the extract is missing
+              or an empty string (the UI's "Do nothing" action), while a null source is still written
+              as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+              `conditional.when: fail_record_when_empty`, which excludes a default.
+
+              On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+              import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+              records is not one), the save stores an omitted key as `null` on every row that has no
+              `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+              conditional — the same default the Mapper UI preselects for those imports. The rule runs
+              when the document is saved, on create and on update, so "Do nothing" on those imports is
+              `conditional.when: extract_not_empty`, not an omitted key.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
                 absent keys: null renders the destination field as JSON null and the
                 empty string renders it as `""` when the extract yields nothing.
-                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" (a missing or `""` source is left out
-                of the output, while a null source is written as null unless
-                `conditional.when` is `extract_not_empty`).
+                Preserve them verbatim when editing or migrating a mapping. Outside
+                the database / csv-xlsx file import set, dropping the key changes
+                runtime behavior from "use null/empty string as default value" to "do
+                nothing" (a missing or `""` source is left out of the output, while a
+                null source is written as null unless `conditional.when` is
+                `extract_not_empty`); inside that set the save writes a dropped key
+                back as `"default": null`, so dropping a stored null changes nothing
+                while dropping a stored `""` or any other explicit value replaces it
+                with null.
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (add `conditional.when:
-                extract_not_empty` to leave a null source out too; without it a null
-                source is written as null); use null → `"default": null`; use empty string or
-                a custom value → `"default": "<value>"`; cause the record to fail →
+                do nothing → `conditional.when: extract_not_empty` with no `default` key
+                (on imports outside the database / csv-xlsx file set the key may simply
+                be omitted, but a null source is then still written as null); 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.
+              - |-
+                On a database or csv / xlsx file import, a row sent with neither a
+                `default` nor one of those conditionals reads back with `"default": null`
+                after the save — create or update — so the destination is written as
+                null; never express "Do nothing" by omission there. A stored
+                `"default": null` on such a row is this save-time default, not a user's
+                choice; keep it when re-sending the row. `"default": null` sent together
+                with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+                `"default" and conditional.when "fail_record_when_empty" cannot be
+                present in mapping simultaneously.`
             examples:
               - N/A
               - '0'
@@ -14703,7 +14764,10 @@ components:
                     not found in the input data.
 
                     Explicit JSON `null` is itself a valid fallback (the element is written as
-                    JSON null); omitting the key means no fallback is applied.
+                    JSON null); omitting the key means no fallback is applied — except on database
+                    and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                    entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                    does on leaf rows.
                   examples:
                     - N/A
                     - '0'

package/dist/tool.yml

@@ -3849,28 +3849,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-            while a null source is still written as null unless `conditional.when` is
-            `extract_not_empty`. Failing the record instead is `conditional.when:
-            fail_record_when_empty`, which excludes a default.
+            action). Outside the database and csv / xlsx file imports described below, omitting the
+            key means no fallback — the field is left out of the output when the extract is missing
+            or an empty string (the UI's "Do nothing" action), while a null source is still written
+            as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+            `conditional.when: fail_record_when_empty`, which excludes a default.
+
+            On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+            import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+            records is not one), the save stores an omitted key as `null` on every row that has no
+            `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+            conditional — the same default the Mapper UI preselects for those imports. The rule runs
+            when the document is saved, on create and on update, so "Do nothing" on those imports is
+            `conditional.when: extract_not_empty`, not an omitted key.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
               absent keys: null renders the destination field as JSON null and the
               empty string renders it as `""` when the extract yields nothing.
-              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" (a missing or `""` source is left out
-              of the output, while a null source is written as null unless
-              `conditional.when` is `extract_not_empty`).
+              Preserve them verbatim when editing or migrating a mapping. Outside
+              the database / csv-xlsx file import set, dropping the key changes
+              runtime behavior from "use null/empty string as default value" to "do
+              nothing" (a missing or `""` source is left out of the output, while a
+              null source is written as null unless `conditional.when` is
+              `extract_not_empty`); inside that set the save writes a dropped key
+              back as `"default": null`, so dropping a stored null changes nothing
+              while dropping a stored `""` or any other explicit value replaces it
+              with null.
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (add `conditional.when:
-              extract_not_empty` to leave a null source out too; without it a null
-              source is written as null); use null → `"default": null`; use empty string or
-              a custom value → `"default": "<value>"`; cause the record to fail →
+              do nothing → `conditional.when: extract_not_empty` with no `default` key
+              (on imports outside the database / csv-xlsx file set the key may simply
+              be omitted, but a null source is then still written as null); 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.
+            - |-
+              On a database or csv / xlsx file import, a row sent with neither a
+              `default` nor one of those conditionals reads back with `"default": null`
+              after the save — create or update — so the destination is written as
+              null; never express "Do nothing" by omission there. A stored
+              `"default": null` on such a row is this save-time default, not a user's
+              choice; keep it when re-sending the row. `"default": null` sent together
+              with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+              `"default" and conditional.when "fail_record_when_empty" cannot be
+              present in mapping simultaneously.`
           examples:
             - N/A
             - '0'
@@ -4277,7 +4300,10 @@ components:
                   not found in the input data.
 
                   Explicit JSON `null` is itself a valid fallback (the element is written as
-                  JSON null); omitting the key means no fallback is applied.
+                  JSON null); omitting the key means no fallback is applied — except on database
+                  and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                  entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                  does on leaf rows.
                 examples:
                   - N/A
                   - '0'
@@ -4947,28 +4973,51 @@ 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 missing or an empty string (the UI's "Do nothing" action),
-              while a null source is still written as null unless `conditional.when` is
-              `extract_not_empty`. Failing the record instead is `conditional.when:
-              fail_record_when_empty`, which excludes a default.
+              action). Outside the database and csv / xlsx file imports described below, omitting the
+              key means no fallback — the field is left out of the output when the extract is missing
+              or an empty string (the UI's "Do nothing" action), while a null source is still written
+              as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
+              `conditional.when: fail_record_when_empty`, which excludes a default.
+
+              On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
+              import with a file-provider assistant or `http.type: file`; an HTTP import that sends
+              records is not one), the save stores an omitted key as `null` on every row that has no
+              `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
+              conditional — the same default the Mapper UI preselects for those imports. The rule runs
+              when the document is saved, on create and on update, so "Do nothing" on those imports is
+              `conditional.when: extract_not_empty`, not an omitted key.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
                 absent keys: null renders the destination field as JSON null and the
                 empty string renders it as `""` when the extract yields nothing.
-                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" (a missing or `""` source is left out
-                of the output, while a null source is written as null unless
-                `conditional.when` is `extract_not_empty`).
+                Preserve them verbatim when editing or migrating a mapping. Outside
+                the database / csv-xlsx file import set, dropping the key changes
+                runtime behavior from "use null/empty string as default value" to "do
+                nothing" (a missing or `""` source is left out of the output, while a
+                null source is written as null unless `conditional.when` is
+                `extract_not_empty`); inside that set the save writes a dropped key
+                back as `"default": null`, so dropping a stored null changes nothing
+                while dropping a stored `""` or any other explicit value replaces it
+                with null.
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (add `conditional.when:
-                extract_not_empty` to leave a null source out too; without it a null
-                source is written as null); use null → `"default": null`; use empty string or
-                a custom value → `"default": "<value>"`; cause the record to fail →
+                do nothing → `conditional.when: extract_not_empty` with no `default` key
+                (on imports outside the database / csv-xlsx file set the key may simply
+                be omitted, but a null source is then still written as null); 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.
+              - |-
+                On a database or csv / xlsx file import, a row sent with neither a
+                `default` nor one of those conditionals reads back with `"default": null`
+                after the save — create or update — so the destination is written as
+                null; never express "Do nothing" by omission there. A stored
+                `"default": null` on such a row is this save-time default, not a user's
+                choice; keep it when re-sending the row. `"default": null` sent together
+                with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
+                `"default" and conditional.when "fail_record_when_empty" cannot be
+                present in mapping simultaneously.`
             examples:
               - N/A
               - '0'
@@ -5375,7 +5424,10 @@ components:
                     not found in the input data.
 
                     Explicit JSON `null` is itself a valid fallback (the element is written as
-                    JSON null); omitting the key means no fallback is applied.
+                    JSON null); omitting the key means no fallback is applied — except on database
+                    and csv / xlsx file imports, where the save stores an omitted key as `null` on an
+                    entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
+                    does on leaf rows.
                   examples:
                     - N/A
                     - '0'
@@ -16177,10 +16229,17 @@ components:
                       - string
                       - 'null'
                     description: |
-                      Path in the source record to extract the value from.
-                      Use dot notation for nested fields (e.g., "address.city").
-                      The platform stores `null` here on fields driven by
-                      `hardCodedValue` instead of an extract path.
+                      Path in the source record to extract the value from, in
+                      dot notation for nested fields (e.g., "address.city").
+                      A bare string is always read as a path, never as a
+                      constant — a path that matches no field sets the
+                      destination field to an empty string (""), written,
+                      not omitted and not the path text, and `discardIfEmpty`
+                      is what skips it; constants belong in `hardCodedValue`,
+                      and the platform stores `null` here on fields driven by
+                      it. A Handlebars template (contains `{{`) reads the
+                      record's fields by bare name; `{{record.<field>}}`
+                      renders an empty string, not the value.
                     examples:
                       - address.city
                   generate:
@@ -16427,9 +16486,14 @@ components:
                             Path from the source record root that produces
                             the value for this sublist column. Paths are
                             always anchored at the source record root —
-                            never relative to a pre-iterated row. The
+                            never relative to a pre-iterated row — and a
+                            bare string is always read as a path, never as a
+                            constant: a path that matches no field leaves the
+                            column absent from every line (unlike a body
+                            field, which is set to ""), never the text
+                            itself. Constants belong in `hardCodedValue`; the
                             platform stores `null` here on fields driven by
-                            `hardCodedValue` instead of an extract path.
+                            it.
                           x-celigo-ai-guidance:
                             - |-
                               Two extract patterns, often mixed in the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.198",
+  "version": "0.2.200",
   "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": "a2635897",
-		"generatedAt": "2026-10-27"
+		"iasCommit": "72f30fe4",
+		"generatedAt": "2026-10-28"
 	},
 	"roots": {
 		"aiagent": 128,