types: make_versioned_base should omit optional None values

[bokelley]

Problem

The new beta.5 make_versioned_base() gives non-required fields a None
default and nullable Python annotation, but its bundled-schema validator sends
an explicitly supplied None into JSON Schema as null. Most AdCP optional
fields permit omission, not null.

Released-wheel reproduction:

from adcp.types.versioned import make_versioned_base

ListCreatives31 = make_versioned_base("3.1", "ListCreativesRequest")

assert ListCreatives31.model_fields["account"].default is None
ListCreatives31(account=None)

Result:

pydantic.ValidationError: account: None is not of type 'object'

The same occurs for context=None, filters=None, and other omittable
top-level fields. This is surprising for a generated Pydantic base whose field
advertises T | None = None, and it breaks normal adopter construction that
passes optional function arguments directly into the request model.

Expected behavior

For a non-required field whose JSON Schema does not admit null, explicit
Python None should normalize to omission before bundled-schema validation and
wire serialization:

request = ListCreatives31(account=None)
assert "account" not in request.model_dump()

Required nullable fields must still preserve None on the wire, so a global
exclude_none=True is insufficient. The factory already computes required
fields and has each property schema; it can distinguish omittable-only fields
from required nullable ones when normalizing the top-level payload.

Please add tests for both sides:

• optional non-nullable ListCreativesRequest.account=None is omitted; and
• a required field whose schema explicitly permits null remains present.

[bokelley]

Triage

Classification: Bug — _VersionedExtensionModel._protocol_payload emits null for explicitly-set None fields because model_fields_set records the explicit assignment even when exclude_unset=True is applied. The bundled JSON Schema then rejects null for fields typed as objects, arrays, or primitives. The declared T | None = None annotation promises that None is accepted but the runtime rejects it.
Bucket(s): validation (no matching label found — flagged for label gap)
Status: ready-to-implement

What the experts said:

• code-reviewer: Fix approach is sound; two blockers to address in implementation: (1) _normalize_optional_none model validator must be defined before _validate_schema_document in the class body (Pydantic executes mode="after" validators in definition order), or it is a no-op; (2) _schema_admits_null must cover all JSON Schema null forms — bare {"type":"null"}, array {"type":["object","null"]}, and anyOf/oneOf with a null alternative — or a misclassified nullable field silently drops None instead of preserving it.
• dx-expert: Change is non-breaking (current behaviour raises unconditionally so no adopter can rely on it); additionally, any optional field whose default=None is set should have its annotation widened to T | None — otherwise Pydantic's field type-check fails before the new validator can run; recommends one changelog entry under "Fixed."

My take: Experts converge. The fix is a well-scoped bug repair in make_versioned_base() with no API breakage. The annotation widening point from the DX expert is a real correctness requirement for the fix to work end-to-end.

Implementation scope:

• src/adcp/types/versioned.py — (a) Add _schema_admits_null(schema, document) helper covering bare-null, array-type, and anyOf/oneOf forms. (b) In make_versioned_base(), after computing guaranteed_fields, build _omit_none_fields: frozenset[str] = optional fields (not in guaranteed_fields) whose schema does not admit null; store as a ClassVar on the generated model. (c) In make_versioned_base(), widen every T | None = None field's annotation to include None (use Optional[annotation] / Union[annotation, None] for any non-required field). (d) In _VersionedExtensionModel, add _omit_none_fields: ClassVar[frozenset[str]] = frozenset(), then add a model_validator(mode="after") named _normalize_optional_none before the existing _validate_schema_document validator; the new validator calls self.model_fields_set.discard(name) for each field in _omit_none_fields whose current value is None.
• tests/ — Add four test cases: (1) optional non-nullable field set to None is absent from model_dump() and does not raise; (2) required nullable field (schema permits null) set to None remains in model_dump() and is included on the wire; (3) anyOf/oneOf-nullable optional field set to None stays in payload; (4) field absent from constructor is still excluded (exclude_unset regression guard).
• Required checks: pytest on touched test subset, mypy src/ (annotation change touches the type surface), ruff check . / black --check ..
• Non-breaking rationale: Raising ValidationError on explicit None is the current (broken) behaviour; no adopter can depend on that path succeeding. The fix aligns runtime semantics with the declared T | None = None contract.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code