This is an automated email from the ASF dual-hosted git repository.
uranusjr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new f2905a7e08f Clarify required params in Lang SDK ADR-0016 (#77081)
f2905a7e08f is described below
commit f2905a7e08f1b0febe4c7c3023c06141ada3c066
Author: Tzu-ping Chung <[email protected]>
AuthorDate: Mon Nov 16 18:33:18 2026 +0800
Clarify required params in Lang SDK ADR-0016 (#77081)
A param entry's example already wrote default only for the parameter
that declares one, but the ADR never said that the key's presence,
not its value, is what tells an optional parameter from a required
one. A reader that treats an absent default the same as "default":
null gets expand_kwargs() wrong either way: a parameter declared with
a None default becomes required, or a required parameter quietly
takes None.
State the rule the format already implies. An entry has a default key
exactly when the stub declares a default, and "default": null is a
None default, not a missing one. Writers emit the key whenever there
is a default, null included, readers go by the key, and anything that
rewrites an entry keeps it. The server's resolution order now says a
parameter still unbound after default fails the task, and an explicit
has-a-default flag is recorded as a rejected alternative.
Nothing emits or reads param entries yet, so no implementation changes.
---
.../adr/lang-sdk/0016-mapped-tasks-across-lang-sdks.md | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
diff --git a/airflow-core/adr/lang-sdk/0016-mapped-tasks-across-lang-sdks.md
b/airflow-core/adr/lang-sdk/0016-mapped-tasks-across-lang-sdks.md
index 7a726d5eee2..9c8ce730367 100644
--- a/airflow-core/adr/lang-sdk/0016-mapped-tasks-across-lang-sdks.md
+++ b/airflow-core/adr/lang-sdk/0016-mapped-tasks-across-lang-sdks.md
@@ -185,12 +185,21 @@ Every kind carries `name` and `value_schema`: the
parameter's name, and the JSON
annotation for a runtime that decodes into machine types. Declaration order is
load-bearing — an SDK
that binds by position, as Go does, has nothing else to go on.
+A `param` entry has a `default` key exactly when the Dag author gives the
parameter a default and
+the call does not set it through `partial()` or `expand()`. `"default": null`
is a default of `None`,
+or its equivalent in the runtime's language, not a missing default: a
parameter that defaults to
+`None` is common in Python. So a writer emits `default` whenever the server
may read it, `null`
+included, a reader tells the two cases apart by the key and not by its value,
and anything that
+reads and rewrites an entry keeps the key's presence. A default declared only
in the task handler,
+in the runtime's language, does not count.
+
A `param` entry is the signature, not the call. The mapped values stay in the
fields Python already
writes: `op_kwargs_expand_input`, a decorated task's name for `expand_input`,
and
`partial_kwargs.op_kwargs`. At `ti_run` the server resolves the entry from
`group_arg` first —
`{group_id, key}`, naming an expand argument of an enclosing mapped task group
— then from those
-fields by `name`, then from `default`. Only `expand_kwargs()` can leave a
parameter unbound until
-run time, so only it needs that fallback.
+fields by `name`, then from `default` if the entry has one; a parameter still
unbound fails the
+task. Only `expand_kwargs()` can leave a parameter unbound until run time, so
only it needs that
+fallback.
Parse time emits `param` just twice: for a mapped stub's parameters, and for a
group member's
argument that names its group. A member's other arguments are ordinary
`literal`, `xcom` or `sequence`
@@ -563,6 +572,11 @@ Every `value` and `default` is checked JSON-serializable
when it is written, so
the language boundary as it stands. Plain JSON also keeps the stored Dag
readable, where the encoded
form wrapped every `value_schema` and every dict-valued `default` in a second
object.
+**An explicit flag beside `default` for whether a parameter has one.** It
would let a writer leave
+out a `None` default, where a typed model's natural spelling cannot tell an
absent key from `null`.
+The flag says nothing the key's presence does not, every SDK's JSON library
can write a present
+`null` with one idiom, and a second field admits entries where the two
disagree.
+
**The server reads the XCom to pick an element.** Under an offloading XCom
backend the row holds only a storage path,
and every `ti_run` of a mapped Lang-SDK task would read XCom values. The
supervisor already reads through the backend.