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.
 

Reply via email to