Skip to content

The only public name for a structured format reference is a subclass that drops three of the generated parent's validators #1398

Closed

Description

@KonstantinMirin

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.

>>> import adcp.types as T
>>> T.LegacyFormatId
<class 'adcp.types.legacy.LegacyFormatId'>
>>> T.LegacyFormatReferenceStructuredObject is T.LegacyFormatId
True
>>> from adcp.types.domains.core.format_id import FormatReferenceStructuredObject as G
>>> [n for n in dir(T) if getattr(T, n, None) is G]
[]                                    # 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:

field generated parent the public Legacy* name
agent_url Strict, AfterValidator(_require_absolute_url), WithJsonSchema({'type':'string','format':'uri'}) no metadata at all
width BeforeValidator(as_json_schema_integer) dropped
height BeforeValidator(as_json_schema_integer) dropped
duration_ms Optional[Annotated[float, Strict]] int | float | None

Why it matters

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:

  1. Export the generated class under a public name — adcp.types.FormatReferenceStructuredObject is the obvious one, and it is currently free.
  2. 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.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 6, 2026
  2. bokelley commented on Oct 6, 2026

    @bokelley
    Contributor

    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.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.


    Triaged by Claude Code. Session: https://claude.ai/code/session_014VYgT1n1eeRGMTYbJUtyt6


    Generated by Claude Code

  3. added
    bugSomething isn't working
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 6, 2026
  4. KonstantinMirin commented on Oct 6, 2026

    @KonstantinMirin
    CollaboratorAuthor

    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.

  5. added a commit that references this issue on Oct 6, 2026
    633559b
  6. added a commit that references this issue on Oct 7, 2026
    3092340
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions