You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
The only public name for a structured format reference is a subclass that drops three of the generated parent's validators #1398
Measured on adcp==9.0.0 built from main + #1392 (9.0.0, adcp.__version__ confirmed).
What I found
The only public names for a structured format reference resolve to a subclass that drops three of the generated parent's validators, and the generated class itself is reachable under no public name.
>>>importadcp.typesasT>>>T.LegacyFormatId<class'adcp.types.legacy.LegacyFormatId'>>>>T.LegacyFormatReferenceStructuredObjectisT.LegacyFormatIdTrue>>>fromadcp.types.domains.core.format_idimportFormatReferenceStructuredObjectasG>>> [nfornindir(T) ifgetattr(T, n, None) isG]
[] # no public name resolves to the generated class>>>issubclass(T.LegacyFormatId, G)
True
Field sets are identical. Four fields differ in validation, and every difference makes the public subclass more permissive than its own parent:
SDK model fields are annotated with the generated class. So an adopter who binds the only available public name gets a type whose validation is laxer than what every SDK model enforces: a relative agent_url validates against adcp.types.LegacyFormatId and is then refused by any model that declares the generated type. The public surface and the library's own contract disagree about the same payload, in the direction that fails late.
duration_ms is the same shape in reverse: under strict mode the parent refuses an int, the public subclass accepts one.
Proposed fix
Two parts, either of which alone closes the hole:
Export the generated class under a public name — adcp.types.FormatReferenceStructuredObject is the obvious one, and it is currently free.
Either give adcp.types.legacy.LegacyFormatId the parent's validators, or stop presenting it as the public name for the concept.
Context
This is the TaskStatus inversion recurring — a public name resolving to a hand-written model while the generated one needs the private tree. That instance is fixed in this build (GeneratedTaskStatus is public, the hand-written enum is deleted); this one is not. Adjacent but distinct from #1364, which was about format_is_supported refusing the reference the SDK's own fields carry.
What the experts said: Deferred before expert consultation (open PR gate — same-author PR overlaps file scope).
My take: The legacy.py comment already describes the intent ("Exported here and deliberately not on adcp.types, which carries the canonical format model instead"), so this is a known gap rather than a design question. PR #1392 by the same author is open, still iterating, and touches legacy.py; the additive fix (export FormatReferenceStructuredObject from adcp.types, align LegacyFormatId validators) is a natural fold into that PR's type-surface work before it merges.
A comment has been left on #1392 describing the fold scope.
Correcting this issue's central argument, which was wrong. The defect is real and the fix is now clearer, but the reasoning I gave for it does not survive measurement, and I want the record straight before anyone acts on it.
What I got wrong
I wrote that every difference makes the public subclass MORE permissive than its parent, and specifically that "a relative agent_url validates against the public name and is then refused by every model that declares the real type."
That is false. I read the field metadata — the subclass's agent_url carries no Annotated metadata — and inferred the behaviour instead of running the validator. Measured:
relative agent_url ("not-absolute")
generated FormatReferenceStructuredObject REFUSES
public adcp.types.LegacyFormatId REFUSES <- I claimed it accepted
width = 300.0
generated FormatReferenceStructuredObject ACCEPTS -> width=300 (SchemaInt BeforeValidator)
public adcp.types.LegacyFormatId REFUSES <- STRICTER, not looser
The subclass refuses the relative URL because it carries its own _validate_agent_url, which duplicates the parent's _require_absolute_url rather than dropping it. So "the public name is weaker" is wrong, and on width/height the direction is the reverse of what I wrote.
What is actually true, and why it is still a defect
Two things stand, and the first is unchanged from the original report:
1. No public name resolves to the generated class.[n for n in dir(adcp.types) if getattr(adcp.types, n, None) is FormatReferenceStructuredObject] returns []. Both adcp.types.LegacyFormatId and adcp.types.LegacyFormatReferenceStructuredObject resolve to adcp.types.legacy.LegacyFormatId.
2. The public name resolves to a clone that diverges from its own parent in BOTH directions. It refuses width: 300.0, which the parent coerces to 300; it accepts duration_ms as an int, which the parent's strict float refuses. Since SDK model fields are annotated with the generated class, a value that validates against the public name can be refused downstream, AND a value the library itself produces can fail to validate against the public name. "Weaker" was the wrong word. "Divergent" is the right one, and divergence in either direction is the bug.
The fix is better than what I proposed
I proposed adding a public export. On this branch that is not needed: adcp.types._generated.FormatReferenceStructuredObject already resolves to the generated class, and the KNOWN_COLLISIONS entry for FormatId already routes it correctly. The hole is only that LegacyFormatId takes the public name with a clone.
And the clone is now dead weight. core/format_id.py carries agent_url: WireUrl (= StrictStr + _require_absolute_url + WithJsonSchema), the same extra='allow', and the same id pattern. So in LegacyFormatId: every redeclaration is either redundant with the parent or a divergence from it, _validate_agent_url duplicates _require_absolute_url, and the model_dump override is a bare super() call.
So: delete the clone, and the public name resolves to the generated class by itself. Derivation by deletion rather than by adding an export — which is also this branch's own stated thesis, that the generated tree IS the public tree.
Credit where due: the width/height direction and the dead-clone finding are not mine; they came out of a second pass that ran the validators instead of reading the annotations, which is what I should have done before filing.
Activity
bokelley commentedon Oct 6, 2026
Triage
Classification: Bug
Bucket(s): validation
Status: deferred — fold candidate
Blocked-on: #1392 — resurfaces on merge
What the experts said: Deferred before expert consultation (open PR gate — same-author PR overlaps file scope).
My take: The
legacy.pycomment already describes the intent ("Exported here and deliberately not onadcp.types, which carries the canonical format model instead"), so this is a known gap rather than a design question. PR #1392 by the same author is open, still iterating, and toucheslegacy.py; the additive fix (exportFormatReferenceStructuredObjectfromadcp.types, alignLegacyFormatIdvalidators) is a natural fold into that PR's type-surface work before it merges.Triaged by Claude Code. Session: https://claude.ai/code/session_014VYgT1n1eeRGMTYbJUtyt6
Generated by Claude Code
KonstantinMirin commentedon Oct 6, 2026
Correcting this issue's central argument, which was wrong. The defect is real and the fix is now clearer, but the reasoning I gave for it does not survive measurement, and I want the record straight before anyone acts on it.
What I got wrong
I wrote that every difference makes the public subclass MORE permissive than its parent, and specifically that "a relative
agent_urlvalidates against the public name and is then refused by every model that declares the real type."That is false. I read the field metadata — the subclass's
agent_urlcarries noAnnotatedmetadata — and inferred the behaviour instead of running the validator. Measured:The subclass refuses the relative URL because it carries its own
_validate_agent_url, which duplicates the parent's_require_absolute_urlrather than dropping it. So "the public name is weaker" is wrong, and onwidth/heightthe direction is the reverse of what I wrote.What is actually true, and why it is still a defect
Two things stand, and the first is unchanged from the original report:
1. No public name resolves to the generated class.
[n for n in dir(adcp.types) if getattr(adcp.types, n, None) is FormatReferenceStructuredObject]returns[]. Bothadcp.types.LegacyFormatIdandadcp.types.LegacyFormatReferenceStructuredObjectresolve toadcp.types.legacy.LegacyFormatId.2. The public name resolves to a clone that diverges from its own parent in BOTH directions. It refuses
width: 300.0, which the parent coerces to300; it acceptsduration_msas anint, which the parent's strictfloatrefuses. Since SDK model fields are annotated with the generated class, a value that validates against the public name can be refused downstream, AND a value the library itself produces can fail to validate against the public name. "Weaker" was the wrong word. "Divergent" is the right one, and divergence in either direction is the bug.The fix is better than what I proposed
I proposed adding a public export. On this branch that is not needed:
adcp.types._generated.FormatReferenceStructuredObjectalready resolves to the generated class, and theKNOWN_COLLISIONSentry forFormatIdalready routes it correctly. The hole is only thatLegacyFormatIdtakes the public name with a clone.And the clone is now dead weight.
core/format_id.pycarriesagent_url: WireUrl(=StrictStr+_require_absolute_url+WithJsonSchema), the sameextra='allow', and the sameidpattern. So inLegacyFormatId: every redeclaration is either redundant with the parent or a divergence from it,_validate_agent_urlduplicates_require_absolute_url, and themodel_dumpoverride is a baresuper()call.So: delete the clone, and the public name resolves to the generated class by itself. Derivation by deletion rather than by adding an export — which is also this branch's own stated thesis, that the generated tree IS the public tree.
Credit where due: the width/height direction and the dead-clone finding are not mine; they came out of a second pass that ran the validators instead of reading the annotations, which is what I should have done before filing.
fix(types): make every Legacy name the generated class, one per respo…
refactor(codegen)!: make the generated domain tree the one public typ…