avoid serializing field: null + docs

src/wf_artifacts/drafts/adapter.py

@@ -42,6 +42,7 @@ def _add_step(builder: WorkflowBuilder, step_id: str, step: DraftStep):
             step.use,
             id=step_id,
             in_map=step.in_,
+            input_values=step.with_,
             out_map=step.out,
             desc=step.desc,
         )

src/wf_artifacts/drafts/models.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any, Literal
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from wf_core.models.conditions import Condition
 
@@ -15,9 +15,33 @@ STEP_KIND_KEYS = frozenset(
 class DraftUseStep(BaseModel):
     """Draft step that calls one externally resolvable workflow capability."""
 
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
     use: str
-    in_: dict[str, str] = Field(default_factory=dict, alias="in")
-    out: dict[str, str] = Field(default_factory=dict)
+    in_: dict[str, str] = Field(
+        default_factory=dict,
+        alias="in",
+        description=(
+            "Source-to-destination map from graph paths to node-local input "
+            "paths. Example: {'input.text': 'message'}. Values must be strings; "
+            "use 'with' for literals."
+        ),
+    )
+    with_: dict[str, Any] = Field(
+        default_factory=dict,
+        alias="with",
+        description=(
+            "Static node-local input values keyed by destination input field/path. "
+            "Example: {'value': 'CLICKED'}."
+        ),
+    )
+    out: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "Source-to-destination map from node-local output paths to workflow "
+            "state destinations. Example: {'echoed': 'state.echoed'}."
+        ),
+    )
     desc: str | None = None
     retry: int | None = Field(default=None, ge=0)
     timeout_seconds: int | None = Field(default=None, gt=0)
@@ -26,6 +50,8 @@ class DraftUseStep(BaseModel):
 class DraftForeachPayload(BaseModel):
     """Payload for one draft foreach step."""
 
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
     over: str
     as_: str = Field(alias="as")
     mode: Literal["serial", "parallel"] = "serial"
@@ -35,12 +61,16 @@ class DraftForeachPayload(BaseModel):
 class DraftForeachStep(BaseModel):
     """Draft step that delegates foreach construction to `WorkflowBuilder`."""
 
+    model_config = ConfigDict(extra="forbid")
+
     foreach: DraftForeachPayload
 
 
 class DraftInterruptPayload(BaseModel):
     """Payload for one draft interrupt step."""
 
+    model_config = ConfigDict(extra="forbid")
+
     kind: str
     request: dict[str, str] = Field(default_factory=dict)
     resume: dict[str, str] = Field(default_factory=dict)
@@ -50,18 +80,24 @@ class DraftInterruptPayload(BaseModel):
 class DraftInterruptStep(BaseModel):
     """Draft step that pauses execution and waits for resume input."""
 
+    model_config = ConfigDict(extra="forbid")
+
     interrupt: DraftInterruptPayload
 
 
 class DraftJoinStep(BaseModel):
     """Draft step that emits the current core join node."""
 
+    model_config = ConfigDict(extra="forbid")
+
     join: JsonObject = Field(default_factory=dict)
 
 
 class DraftWhenPayload(BaseModel):
     """Payload for one boolean draft decision."""
 
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
     if_: Condition = Field(alias="if")
     then: str
     otherwise: str = "__end__"
@@ -70,12 +106,16 @@ class DraftWhenPayload(BaseModel):
 class DraftWhenStep(BaseModel):
     """Draft step that delegates one boolean decision to `WorkflowBuilder.when`."""
 
+    model_config = ConfigDict(extra="forbid")
+
     when: DraftWhenPayload
 
 
 class DraftChooseClause(BaseModel):
     """One ordered boolean clause in a draft choose decision."""
 
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
     if_: Condition = Field(alias="if")
     then: str
 
@@ -83,6 +123,8 @@ class DraftChooseClause(BaseModel):
 class DraftChoosePayload(BaseModel):
     """Payload for an ordered first-true draft decision."""
 
+    model_config = ConfigDict(extra="forbid")
+
     clauses: list[DraftChooseClause] = Field(min_length=1)
     default: str = "__end__"
 
@@ -90,12 +132,16 @@ class DraftChoosePayload(BaseModel):
 class DraftChooseStep(BaseModel):
     """Draft step that delegates ordered decisions to `WorkflowBuilder.choose`."""
 
+    model_config = ConfigDict(extra="forbid")
+
     choose: DraftChoosePayload
 
 
 class DraftMatchCase(BaseModel):
     """One ordered equality case in a draft match decision."""
 
+    model_config = ConfigDict(extra="forbid")
+
     equals: Any
     then: str
 
@@ -103,6 +149,8 @@ class DraftMatchCase(BaseModel):
 class DraftMatchPayload(BaseModel):
     """Payload for matching one graph value against ordered equality cases."""
 
+    model_config = ConfigDict(extra="forbid")
+
     value: str
     cases: list[DraftMatchCase] = Field(min_length=1)
     default: str = "__end__"
@@ -111,6 +159,8 @@ class DraftMatchPayload(BaseModel):
 class DraftMatchStep(BaseModel):
     """Draft step that delegates equality decisions to `WorkflowBuilder.match`."""
 
+    model_config = ConfigDict(extra="forbid")
+
     match: DraftMatchPayload