@celigo/api-specs 0.2.197 → 0.2.199

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/ai-agent.yml CHANGED
@@ -2831,28 +2831,51 @@ components:
2831
2831
 
2832
2832
  Explicit JSON `null` is itself a valid fallback: the destination field is written as
2833
2833
  JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
2834
- action). Omitting the key entirely means no fallback — the field is left out of the
2835
- output when the extract is missing or an empty string (the UI's "Do nothing" action),
2836
- while a null source is still written as null unless `conditional.when` is
2837
- `extract_not_empty`. Failing the record instead is `conditional.when:
2838
- fail_record_when_empty`, which excludes a default.
2834
+ action). Outside the database and csv / xlsx file imports described below, omitting the
2835
+ key means no fallback — the field is left out of the output when the extract is missing
2836
+ or an empty string (the UI's "Do nothing" action), while a null source is still written
2837
+ as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
2838
+ `conditional.when: fail_record_when_empty`, which excludes a default.
2839
+
2840
+ On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
2841
+ import with a file-provider assistant or `http.type: file`; an HTTP import that sends
2842
+ records is not one), the save stores an omitted key as `null` on every row that has no
2843
+ `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
2844
+ conditional — the same default the Mapper UI preselects for those imports. The rule runs
2845
+ when the document is saved, on create and on update, so "Do nothing" on those imports is
2846
+ `conditional.when: extract_not_empty`, not an omitted key.
2839
2847
  x-celigo-ai-guidance:
2840
2848
  - |-
2841
2849
  `"default": null` and `"default": ""` are distinct saved values, not
2842
2850
  absent keys: null renders the destination field as JSON null and the
2843
2851
  empty string renders it as `""` when the extract yields nothing.
2844
- Preserve them verbatim when editing or migrating a mapping — dropping
2845
- the key changes runtime behavior from "use null/empty string as
2846
- default value" to "do nothing" (a missing or `""` source is left out
2847
- of the output, while a null source is written as null unless
2848
- `conditional.when` is `extract_not_empty`).
2852
+ Preserve them verbatim when editing or migrating a mapping. Outside
2853
+ the database / csv-xlsx file import set, dropping the key changes
2854
+ runtime behavior from "use null/empty string as default value" to "do
2855
+ nothing" (a missing or `""` source is left out of the output, while a
2856
+ null source is written as null unless `conditional.when` is
2857
+ `extract_not_empty`); inside that set the save writes a dropped key
2858
+ back as `"default": null`, so dropping a stored null changes nothing
2859
+ while dropping a stored `""` or any other explicit value replaces it
2860
+ with null.
2849
2861
  - |-
2850
2862
  The four "Action to take if source field has no value" choices map to:
2851
- do nothing → no `default` key (add `conditional.when:
2852
- extract_not_empty` to leave a null source out too; without it a null
2853
- source is written as null); use null → `"default": null`; use empty string or
2854
- a custom value → `"default": "<value>"`; cause the record to fail →
2863
+ do nothing → `conditional.when: extract_not_empty` with no `default` key
2864
+ (on imports outside the database / csv-xlsx file set the key may simply
2865
+ be omitted, but a null source is then still written as null); use null →
2866
+ `"default": null`; use empty string or a custom value →
2867
+ `"default": "<value>"`; cause the record to fail →
2855
2868
  `conditional.when: fail_record_when_empty` with no `default` key.
2869
+ - |-
2870
+ On a database or csv / xlsx file import, a row sent with neither a
2871
+ `default` nor one of those conditionals reads back with `"default": null`
2872
+ after the save — create or update — so the destination is written as
2873
+ null; never express "Do nothing" by omission there. A stored
2874
+ `"default": null` on such a row is this save-time default, not a user's
2875
+ choice; keep it when re-sending the row. `"default": null` sent together
2876
+ with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
2877
+ `"default" and conditional.when "fail_record_when_empty" cannot be
2878
+ present in mapping simultaneously.`
2856
2879
  examples:
2857
2880
  - N/A
2858
2881
  - '0'
@@ -3259,7 +3282,10 @@ components:
3259
3282
  not found in the input data.
3260
3283
 
3261
3284
  Explicit JSON `null` is itself a valid fallback (the element is written as
3262
- JSON null); omitting the key means no fallback is applied.
3285
+ JSON null); omitting the key means no fallback is applied — except on database
3286
+ and csv / xlsx file imports, where the save stores an omitted key as `null` on an
3287
+ entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
3288
+ does on leaf rows.
3263
3289
  examples:
3264
3290
  - N/A
3265
3291
  - '0'
@@ -3929,28 +3955,51 @@ components:
3929
3955
 
3930
3956
  Explicit JSON `null` is itself a valid fallback: the destination field is written as
3931
3957
  JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
3932
- action). Omitting the key entirely means no fallback — the field is left out of the
3933
- output when the extract is missing or an empty string (the UI's "Do nothing" action),
3934
- while a null source is still written as null unless `conditional.when` is
3935
- `extract_not_empty`. Failing the record instead is `conditional.when:
3936
- fail_record_when_empty`, which excludes a default.
3958
+ action). Outside the database and csv / xlsx file imports described below, omitting the
3959
+ key means no fallback — the field is left out of the output when the extract is missing
3960
+ or an empty string (the UI's "Do nothing" action), while a null source is still written
3961
+ as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
3962
+ `conditional.when: fail_record_when_empty`, which excludes a default.
3963
+
3964
+ On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
3965
+ import with a file-provider assistant or `http.type: file`; an HTTP import that sends
3966
+ records is not one), the save stores an omitted key as `null` on every row that has no
3967
+ `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
3968
+ conditional — the same default the Mapper UI preselects for those imports. The rule runs
3969
+ when the document is saved, on create and on update, so "Do nothing" on those imports is
3970
+ `conditional.when: extract_not_empty`, not an omitted key.
3937
3971
  x-celigo-ai-guidance:
3938
3972
  - |-
3939
3973
  `"default": null` and `"default": ""` are distinct saved values, not
3940
3974
  absent keys: null renders the destination field as JSON null and the
3941
3975
  empty string renders it as `""` when the extract yields nothing.
3942
- Preserve them verbatim when editing or migrating a mapping — dropping
3943
- the key changes runtime behavior from "use null/empty string as
3944
- default value" to "do nothing" (a missing or `""` source is left out
3945
- of the output, while a null source is written as null unless
3946
- `conditional.when` is `extract_not_empty`).
3976
+ Preserve them verbatim when editing or migrating a mapping. Outside
3977
+ the database / csv-xlsx file import set, dropping the key changes
3978
+ runtime behavior from "use null/empty string as default value" to "do
3979
+ nothing" (a missing or `""` source is left out of the output, while a
3980
+ null source is written as null unless `conditional.when` is
3981
+ `extract_not_empty`); inside that set the save writes a dropped key
3982
+ back as `"default": null`, so dropping a stored null changes nothing
3983
+ while dropping a stored `""` or any other explicit value replaces it
3984
+ with null.
3947
3985
  - |-
3948
3986
  The four "Action to take if source field has no value" choices map to:
3949
- do nothing → no `default` key (add `conditional.when:
3950
- extract_not_empty` to leave a null source out too; without it a null
3951
- source is written as null); use null → `"default": null`; use empty string or
3952
- a custom value → `"default": "<value>"`; cause the record to fail →
3987
+ do nothing → `conditional.when: extract_not_empty` with no `default` key
3988
+ (on imports outside the database / csv-xlsx file set the key may simply
3989
+ be omitted, but a null source is then still written as null); use null →
3990
+ `"default": null`; use empty string or a custom value →
3991
+ `"default": "<value>"`; cause the record to fail →
3953
3992
  `conditional.when: fail_record_when_empty` with no `default` key.
3993
+ - |-
3994
+ On a database or csv / xlsx file import, a row sent with neither a
3995
+ `default` nor one of those conditionals reads back with `"default": null`
3996
+ after the save — create or update — so the destination is written as
3997
+ null; never express "Do nothing" by omission there. A stored
3998
+ `"default": null` on such a row is this save-time default, not a user's
3999
+ choice; keep it when re-sending the row. `"default": null` sent together
4000
+ with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
4001
+ `"default" and conditional.when "fail_record_when_empty" cannot be
4002
+ present in mapping simultaneously.`
3954
4003
  examples:
3955
4004
  - N/A
3956
4005
  - '0'
@@ -4357,7 +4406,10 @@ components:
4357
4406
  not found in the input data.
4358
4407
 
4359
4408
  Explicit JSON `null` is itself a valid fallback (the element is written as
4360
- JSON null); omitting the key means no fallback is applied.
4409
+ JSON null); omitting the key means no fallback is applied — except on database
4410
+ and csv / xlsx file imports, where the save stores an omitted key as `null` on an
4411
+ entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
4412
+ does on leaf rows.
4361
4413
  examples:
4362
4414
  - N/A
4363
4415
  - '0'
package/dist/api.yml CHANGED
@@ -2909,28 +2909,51 @@ components:
2909
2909
 
2910
2910
  Explicit JSON `null` is itself a valid fallback: the destination field is written as
2911
2911
  JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
2912
- action). Omitting the key entirely means no fallback — the field is left out of the
2913
- output when the extract is missing or an empty string (the UI's "Do nothing" action),
2914
- while a null source is still written as null unless `conditional.when` is
2915
- `extract_not_empty`. Failing the record instead is `conditional.when:
2916
- fail_record_when_empty`, which excludes a default.
2912
+ action). Outside the database and csv / xlsx file imports described below, omitting the
2913
+ key means no fallback — the field is left out of the output when the extract is missing
2914
+ or an empty string (the UI's "Do nothing" action), while a null source is still written
2915
+ as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
2916
+ `conditional.when: fail_record_when_empty`, which excludes a default.
2917
+
2918
+ On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
2919
+ import with a file-provider assistant or `http.type: file`; an HTTP import that sends
2920
+ records is not one), the save stores an omitted key as `null` on every row that has no
2921
+ `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
2922
+ conditional — the same default the Mapper UI preselects for those imports. The rule runs
2923
+ when the document is saved, on create and on update, so "Do nothing" on those imports is
2924
+ `conditional.when: extract_not_empty`, not an omitted key.
2917
2925
  x-celigo-ai-guidance:
2918
2926
  - |-
2919
2927
  `"default": null` and `"default": ""` are distinct saved values, not
2920
2928
  absent keys: null renders the destination field as JSON null and the
2921
2929
  empty string renders it as `""` when the extract yields nothing.
2922
- Preserve them verbatim when editing or migrating a mapping — dropping
2923
- the key changes runtime behavior from "use null/empty string as
2924
- default value" to "do nothing" (a missing or `""` source is left out
2925
- of the output, while a null source is written as null unless
2926
- `conditional.when` is `extract_not_empty`).
2930
+ Preserve them verbatim when editing or migrating a mapping. Outside
2931
+ the database / csv-xlsx file import set, dropping the key changes
2932
+ runtime behavior from "use null/empty string as default value" to "do
2933
+ nothing" (a missing or `""` source is left out of the output, while a
2934
+ null source is written as null unless `conditional.when` is
2935
+ `extract_not_empty`); inside that set the save writes a dropped key
2936
+ back as `"default": null`, so dropping a stored null changes nothing
2937
+ while dropping a stored `""` or any other explicit value replaces it
2938
+ with null.
2927
2939
  - |-
2928
2940
  The four "Action to take if source field has no value" choices map to:
2929
- do nothing → no `default` key (add `conditional.when:
2930
- extract_not_empty` to leave a null source out too; without it a null
2931
- source is written as null); use null → `"default": null`; use empty string or
2932
- a custom value → `"default": "<value>"`; cause the record to fail →
2941
+ do nothing → `conditional.when: extract_not_empty` with no `default` key
2942
+ (on imports outside the database / csv-xlsx file set the key may simply
2943
+ be omitted, but a null source is then still written as null); use null →
2944
+ `"default": null`; use empty string or a custom value →
2945
+ `"default": "<value>"`; cause the record to fail →
2933
2946
  `conditional.when: fail_record_when_empty` with no `default` key.
2947
+ - |-
2948
+ On a database or csv / xlsx file import, a row sent with neither a
2949
+ `default` nor one of those conditionals reads back with `"default": null`
2950
+ after the save — create or update — so the destination is written as
2951
+ null; never express "Do nothing" by omission there. A stored
2952
+ `"default": null` on such a row is this save-time default, not a user's
2953
+ choice; keep it when re-sending the row. `"default": null` sent together
2954
+ with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
2955
+ `"default" and conditional.when "fail_record_when_empty" cannot be
2956
+ present in mapping simultaneously.`
2934
2957
  examples:
2935
2958
  - N/A
2936
2959
  - '0'
@@ -3337,7 +3360,10 @@ components:
3337
3360
  not found in the input data.
3338
3361
 
3339
3362
  Explicit JSON `null` is itself a valid fallback (the element is written as
3340
- JSON null); omitting the key means no fallback is applied.
3363
+ JSON null); omitting the key means no fallback is applied — except on database
3364
+ and csv / xlsx file imports, where the save stores an omitted key as `null` on an
3365
+ entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
3366
+ does on leaf rows.
3341
3367
  examples:
3342
3368
  - N/A
3343
3369
  - '0'
@@ -4007,28 +4033,51 @@ components:
4007
4033
 
4008
4034
  Explicit JSON `null` is itself a valid fallback: the destination field is written as
4009
4035
  JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
4010
- action). Omitting the key entirely means no fallback — the field is left out of the
4011
- output when the extract is missing or an empty string (the UI's "Do nothing" action),
4012
- while a null source is still written as null unless `conditional.when` is
4013
- `extract_not_empty`. Failing the record instead is `conditional.when:
4014
- fail_record_when_empty`, which excludes a default.
4036
+ action). Outside the database and csv / xlsx file imports described below, omitting the
4037
+ key means no fallback — the field is left out of the output when the extract is missing
4038
+ or an empty string (the UI's "Do nothing" action), while a null source is still written
4039
+ as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
4040
+ `conditional.when: fail_record_when_empty`, which excludes a default.
4041
+
4042
+ On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
4043
+ import with a file-provider assistant or `http.type: file`; an HTTP import that sends
4044
+ records is not one), the save stores an omitted key as `null` on every row that has no
4045
+ `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
4046
+ conditional — the same default the Mapper UI preselects for those imports. The rule runs
4047
+ when the document is saved, on create and on update, so "Do nothing" on those imports is
4048
+ `conditional.when: extract_not_empty`, not an omitted key.
4015
4049
  x-celigo-ai-guidance:
4016
4050
  - |-
4017
4051
  `"default": null` and `"default": ""` are distinct saved values, not
4018
4052
  absent keys: null renders the destination field as JSON null and the
4019
4053
  empty string renders it as `""` when the extract yields nothing.
4020
- Preserve them verbatim when editing or migrating a mapping — dropping
4021
- the key changes runtime behavior from "use null/empty string as
4022
- default value" to "do nothing" (a missing or `""` source is left out
4023
- of the output, while a null source is written as null unless
4024
- `conditional.when` is `extract_not_empty`).
4054
+ Preserve them verbatim when editing or migrating a mapping. Outside
4055
+ the database / csv-xlsx file import set, dropping the key changes
4056
+ runtime behavior from "use null/empty string as default value" to "do
4057
+ nothing" (a missing or `""` source is left out of the output, while a
4058
+ null source is written as null unless `conditional.when` is
4059
+ `extract_not_empty`); inside that set the save writes a dropped key
4060
+ back as `"default": null`, so dropping a stored null changes nothing
4061
+ while dropping a stored `""` or any other explicit value replaces it
4062
+ with null.
4025
4063
  - |-
4026
4064
  The four "Action to take if source field has no value" choices map to:
4027
- do nothing → no `default` key (add `conditional.when:
4028
- extract_not_empty` to leave a null source out too; without it a null
4029
- source is written as null); use null → `"default": null`; use empty string or
4030
- a custom value → `"default": "<value>"`; cause the record to fail →
4065
+ do nothing → `conditional.when: extract_not_empty` with no `default` key
4066
+ (on imports outside the database / csv-xlsx file set the key may simply
4067
+ be omitted, but a null source is then still written as null); use null →
4068
+ `"default": null`; use empty string or a custom value →
4069
+ `"default": "<value>"`; cause the record to fail →
4031
4070
  `conditional.when: fail_record_when_empty` with no `default` key.
4071
+ - |-
4072
+ On a database or csv / xlsx file import, a row sent with neither a
4073
+ `default` nor one of those conditionals reads back with `"default": null`
4074
+ after the save — create or update — so the destination is written as
4075
+ null; never express "Do nothing" by omission there. A stored
4076
+ `"default": null` on such a row is this save-time default, not a user's
4077
+ choice; keep it when re-sending the row. `"default": null` sent together
4078
+ with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
4079
+ `"default" and conditional.when "fail_record_when_empty" cannot be
4080
+ present in mapping simultaneously.`
4032
4081
  examples:
4033
4082
  - N/A
4034
4083
  - '0'
@@ -4435,7 +4484,10 @@ components:
4435
4484
  not found in the input data.
4436
4485
 
4437
4486
  Explicit JSON `null` is itself a valid fallback (the element is written as
4438
- JSON null); omitting the key means no fallback is applied.
4487
+ JSON null); omitting the key means no fallback is applied — except on database
4488
+ and csv / xlsx file imports, where the save stores an omitted key as `null` on an
4489
+ entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
4490
+ does on leaf rows.
4439
4491
  examples:
4440
4492
  - N/A
4441
4493
  - '0'
@@ -805,28 +805,51 @@ components:
805
805
 
806
806
  Explicit JSON `null` is itself a valid fallback: the destination field is written as
807
807
  JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
808
- action). Omitting the key entirely means no fallback — the field is left out of the
809
- output when the extract is missing or an empty string (the UI's "Do nothing" action),
810
- while a null source is still written as null unless `conditional.when` is
811
- `extract_not_empty`. Failing the record instead is `conditional.when:
812
- fail_record_when_empty`, which excludes a default.
808
+ action). Outside the database and csv / xlsx file imports described below, omitting the
809
+ key means no fallback — the field is left out of the output when the extract is missing
810
+ or an empty string (the UI's "Do nothing" action), while a null source is still written
811
+ as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
812
+ `conditional.when: fail_record_when_empty`, which excludes a default.
813
+
814
+ On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
815
+ import with a file-provider assistant or `http.type: file`; an HTTP import that sends
816
+ records is not one), the save stores an omitted key as `null` on every row that has no
817
+ `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
818
+ conditional — the same default the Mapper UI preselects for those imports. The rule runs
819
+ when the document is saved, on create and on update, so "Do nothing" on those imports is
820
+ `conditional.when: extract_not_empty`, not an omitted key.
813
821
  x-celigo-ai-guidance:
814
822
  - |-
815
823
  `"default": null` and `"default": ""` are distinct saved values, not
816
824
  absent keys: null renders the destination field as JSON null and the
817
825
  empty string renders it as `""` when the extract yields nothing.
818
- Preserve them verbatim when editing or migrating a mapping — dropping
819
- the key changes runtime behavior from "use null/empty string as
820
- default value" to "do nothing" (a missing or `""` source is left out
821
- of the output, while a null source is written as null unless
822
- `conditional.when` is `extract_not_empty`).
826
+ Preserve them verbatim when editing or migrating a mapping. Outside
827
+ the database / csv-xlsx file import set, dropping the key changes
828
+ runtime behavior from "use null/empty string as default value" to "do
829
+ nothing" (a missing or `""` source is left out of the output, while a
830
+ null source is written as null unless `conditional.when` is
831
+ `extract_not_empty`); inside that set the save writes a dropped key
832
+ back as `"default": null`, so dropping a stored null changes nothing
833
+ while dropping a stored `""` or any other explicit value replaces it
834
+ with null.
823
835
  - |-
824
836
  The four "Action to take if source field has no value" choices map to:
825
- do nothing → no `default` key (add `conditional.when:
826
- extract_not_empty` to leave a null source out too; without it a null
827
- source is written as null); use null → `"default": null`; use empty string or
828
- a custom value → `"default": "<value>"`; cause the record to fail →
837
+ do nothing → `conditional.when: extract_not_empty` with no `default` key
838
+ (on imports outside the database / csv-xlsx file set the key may simply
839
+ be omitted, but a null source is then still written as null); use null →
840
+ `"default": null`; use empty string or a custom value →
841
+ `"default": "<value>"`; cause the record to fail →
829
842
  `conditional.when: fail_record_when_empty` with no `default` key.
843
+ - |-
844
+ On a database or csv / xlsx file import, a row sent with neither a
845
+ `default` nor one of those conditionals reads back with `"default": null`
846
+ after the save — create or update — so the destination is written as
847
+ null; never express "Do nothing" by omission there. A stored
848
+ `"default": null` on such a row is this save-time default, not a user's
849
+ choice; keep it when re-sending the row. `"default": null` sent together
850
+ with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
851
+ `"default" and conditional.when "fail_record_when_empty" cannot be
852
+ present in mapping simultaneously.`
830
853
  examples:
831
854
  - N/A
832
855
  - '0'
@@ -1233,7 +1256,10 @@ components:
1233
1256
  not found in the input data.
1234
1257
 
1235
1258
  Explicit JSON `null` is itself a valid fallback (the element is written as
1236
- JSON null); omitting the key means no fallback is applied.
1259
+ JSON null); omitting the key means no fallback is applied — except on database
1260
+ and csv / xlsx file imports, where the save stores an omitted key as `null` on an
1261
+ entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
1262
+ does on leaf rows.
1237
1263
  examples:
1238
1264
  - N/A
1239
1265
  - '0'
@@ -1903,28 +1929,51 @@ components:
1903
1929
 
1904
1930
  Explicit JSON `null` is itself a valid fallback: the destination field is written as
1905
1931
  JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
1906
- action). Omitting the key entirely means no fallback — the field is left out of the
1907
- output when the extract is missing or an empty string (the UI's "Do nothing" action),
1908
- while a null source is still written as null unless `conditional.when` is
1909
- `extract_not_empty`. Failing the record instead is `conditional.when:
1910
- fail_record_when_empty`, which excludes a default.
1932
+ action). Outside the database and csv / xlsx file imports described below, omitting the
1933
+ key means no fallback — the field is left out of the output when the extract is missing
1934
+ or an empty string (the UI's "Do nothing" action), while a null source is still written
1935
+ as null unless `conditional.when` is `extract_not_empty`. Failing the record instead is
1936
+ `conditional.when: fail_record_when_empty`, which excludes a default.
1937
+
1938
+ On database imports (rdbms, jdbc) and csv / xlsx file imports (such as ftp, or an HTTP
1939
+ import with a file-provider assistant or `http.type: file`; an HTTP import that sends
1940
+ records is not one), the save stores an omitted key as `null` on every row that has no
1941
+ `hardCodedValue`, no `lookupName` and no `extract_not_empty` / `fail_record_when_empty`
1942
+ conditional — the same default the Mapper UI preselects for those imports. The rule runs
1943
+ when the document is saved, on create and on update, so "Do nothing" on those imports is
1944
+ `conditional.when: extract_not_empty`, not an omitted key.
1911
1945
  x-celigo-ai-guidance:
1912
1946
  - |-
1913
1947
  `"default": null` and `"default": ""` are distinct saved values, not
1914
1948
  absent keys: null renders the destination field as JSON null and the
1915
1949
  empty string renders it as `""` when the extract yields nothing.
1916
- Preserve them verbatim when editing or migrating a mapping — dropping
1917
- the key changes runtime behavior from "use null/empty string as
1918
- default value" to "do nothing" (a missing or `""` source is left out
1919
- of the output, while a null source is written as null unless
1920
- `conditional.when` is `extract_not_empty`).
1950
+ Preserve them verbatim when editing or migrating a mapping. Outside
1951
+ the database / csv-xlsx file import set, dropping the key changes
1952
+ runtime behavior from "use null/empty string as default value" to "do
1953
+ nothing" (a missing or `""` source is left out of the output, while a
1954
+ null source is written as null unless `conditional.when` is
1955
+ `extract_not_empty`); inside that set the save writes a dropped key
1956
+ back as `"default": null`, so dropping a stored null changes nothing
1957
+ while dropping a stored `""` or any other explicit value replaces it
1958
+ with null.
1921
1959
  - |-
1922
1960
  The four "Action to take if source field has no value" choices map to:
1923
- do nothing → no `default` key (add `conditional.when:
1924
- extract_not_empty` to leave a null source out too; without it a null
1925
- source is written as null); use null → `"default": null`; use empty string or
1926
- a custom value → `"default": "<value>"`; cause the record to fail →
1961
+ do nothing → `conditional.when: extract_not_empty` with no `default` key
1962
+ (on imports outside the database / csv-xlsx file set the key may simply
1963
+ be omitted, but a null source is then still written as null); use null →
1964
+ `"default": null`; use empty string or a custom value →
1965
+ `"default": "<value>"`; cause the record to fail →
1927
1966
  `conditional.when: fail_record_when_empty` with no `default` key.
1967
+ - |-
1968
+ On a database or csv / xlsx file import, a row sent with neither a
1969
+ `default` nor one of those conditionals reads back with `"default": null`
1970
+ after the save — create or update — so the destination is written as
1971
+ null; never express "Do nothing" by omission there. A stored
1972
+ `"default": null` on such a row is this save-time default, not a user's
1973
+ choice; keep it when re-sending the row. `"default": null` sent together
1974
+ with `fail_record_when_empty` is rejected with 422 `unsupported_mapping`
1975
+ `"default" and conditional.when "fail_record_when_empty" cannot be
1976
+ present in mapping simultaneously.`
1928
1977
  examples:
1929
1978
  - N/A
1930
1979
  - '0'
@@ -2331,7 +2380,10 @@ components:
2331
2380
  not found in the input data.
2332
2381
 
2333
2382
  Explicit JSON `null` is itself a valid fallback (the element is written as
2334
- JSON null); omitting the key means no fallback is applied.
2383
+ JSON null); omitting the key means no fallback is applied — except on database
2384
+ and csv / xlsx file imports, where the save stores an omitted key as `null` on an
2385
+ entry without an `extract_not_empty` / `fail_record_when_empty` conditional, as it
2386
+ does on leaf rows.
2335
2387
  examples:
2336
2388
  - N/A
2337
2389
  - '0'