Skip to content

fix: accept unknown enum values in response models - #43

Open
alisezer wants to merge 1 commit into
xdevplatform:mainfrom
alisezer:fix/open-response-enums
Open

alisezer wants to merge 1 commit into
xdevplatform:mainfrom
alisezer:fix/open-response-enums

Conversation

@alisezer

Copy link
Copy Markdown

Problem

Since #36, spec enums render as strict Literal[...] (Python) and literal unions (TypeScript). When the server sends a value the spec doesn't list, the whole response fails to validate in Python, even though the models allow extra fields (extra="allow").

This is happening now. Requested with post.fields=referenced_posts, the API returns referenced_posts[].type == "reposted", and any timeline page that contains a repost fails:

pydantic_core._pydantic_core.ValidationError: 1 validation error for GetListsPostsResponse
data.0.referenced_posts.0.type
  Input should be 'retweeted', 'quoted' or 'replied_to' [type=literal_error, input_value='reposted', input_type=str]

The published spec (https://api.x.com/2/openapi.json, info.version 2.168, and the pinned specs/openapi.json 2.167) still lists only retweeted | quoted | replied_to for PostReferencedPosts.items.type. Reported in xdevplatform/xdk-python#7.

Change

Enums inside component schemas that an operation response can reach become open enums:

Before After
Python Literal["retweeted", "quoted", "replied_to"] Union[Literal["retweeted", "quoted", "replied_to"], str]
TypeScript "retweeted" | "quoted" | "replied_to" "retweeted" | "quoted" | "replied_to" | (string & {})

Known values stay visible to type checkers and editors (pyright shows str | Literal['retweeted', 'quoted', 'replied_to'], and TS keeps autocomplete). Unknown strings validate instead of failing the page. Non-strings are still rejected.

How request and response are told apart: the generator serializes each operation's responses. Serialized $refs carry their resolved bodies, so a single walk collects every component schema a response can reach (types::referenced_schema_names). py_schema_module and ts_schema_declarations take that set and mark enums in those schemas as open (x-xdk-open-enum). Everything else is unchanged:

  • Parameters stay strict. They render through py_type/ts_type, which never open enums. For example, post_fields: Optional[List[Literal["article", "article_title", ...]]] in xdk/lists/client.py (and postFields?: Array<"article" | ...> in TS) is unchanged.
  • Request-body schemas stay strict. In the current spec, no enum-bearing component is shared between requests and responses. The 13 request-only schemas (CreatePostsRequest, MediaUploadRequest, CreateComplianceJobsRequest, ...) keep Literals.
  • Single-value enums stay strict. They act as constants and discriminators. Problem is a oneOf discriminated on single-value type URIs, and opening those would break TS narrowing and let pydantic's smart-mode union pick the wrong *Problem class.

With the pinned spec, exactly four fields change, in both SDKs' schemas modules: PostReferencedPosts[].type, PostWithheld.scope, ActivitySubscriptionFilter.direction and UserConnectionStatus. Per-tag models and clients are unchanged, aside from the existing run-to-run operation-order nondeterminism.

Tests

  • New xdk-lib unit tests: open enums in both languages, strict enums outside the set and via py_type_of/ts_type_of, single-value enums staying strict, and ref-closure collection. cargo test: 184 passed (180 before), 0 failed.
  • cargo fmt --all -- --check and cargo clippy --all --all-targets --all-features -- -D warnings: clean.
  • Python SDK (generated from specs/openapi.json): 1276/1276 passed, the same as before.
  • TypeScript SDK: build, tsc --noEmit, and 1178/1178 tests passed, the same as before.
  • Local repro against the generated SDKs (synthetic IDs, not committed):
    • Python: a GetPostsResponse page with {"id": "1", "type": "reposted"} fails before and validates after. "quoted" still validates. A non-string type is still rejected.
    • TS: a GetPostsResponse literal with type: 'reposted' fails tsc before and compiles after. postFields: ['not_a_field'] is still a type error.

Notes / open questions

  • The spec still needs fixing on X's side. reposted should be added to PostReferencedPosts.items.type. This PR stops a spec lag from breaking every page; it doesn't replace fixing the spec.
  • TypeScript trade-off: with | (string & {}), t === "quoted" no longer narrows t to the literal, and a typo in a comparison isn't caught. That is inherent to any open type. Mypy also collapses Union[Literal[...], str] to str, while pyright/Pylance keep the literals.
  • If you would rather keep strict enums by default, this could sit behind a flag in xdk-config.toml. I'm happy to change it, but a strict default means the next new server value breaks users again until the spec and SDK catch up.
  • Enums inline in a response body (not a component) aren't covered. None exist in the current spec.
  • Unknown Problem types in errors would still fail validation. That needs a different fix (for example a fallback variant) and is out of scope here.

Refs xdevplatform/xdk-python#7

🤖 Generated with Claude Code

The X API can return enum values its published spec does not list yet.
With `post.fields=referenced_posts` the server now sends
`referenced_posts[].type == "reposted"`, while the spec still lists only
retweeted | quoted | replied_to, so every Python response containing a
repost fails validation:

    Input should be 'retweeted', 'quoted' or 'replied_to'
    [type=literal_error, input_value='reposted', input_type=str]

Render enums in component schemas reachable from an operation response
as open enums: `Union[Literal[...], str]` in Python and
`"a" | "b" | (string & {})` in TypeScript. Known values stay visible to
type checkers and editors; unknown values validate instead of failing
the whole response.

Request-only schemas and parameter enums stay strict literals, and
single-value enums stay strict since they act as constants or union
discriminators (e.g. the Problem `type` URIs).

Refs xdevplatform/xdk-python#7

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@CLAassistant

CLAassistant commented Sep 25, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@alisezer

Copy link
Copy Markdown
Author

A note on CI, since it generates from the live spec (--latest true, currently 2.168) rather than the pinned specs/openapi.json (2.167) I used for the counts in the description:

  • Against the live spec, TypeScript passes 1288/1288 on both main and this branch.

  • Python gives 1380 passed / 2 failed on both main (84c2654) and this branch. The failures are unrelated to this change:

    • tests/compliance/test_contracts.py::TestComplianceContracts::test_upload_job_submission_request_structure
    • tests/compliance/test_contracts.py::TestComplianceContracts::test_upload_job_submission_response_structure

    Both fail with ImportError: cannot import name 'UploadJobSubmissionRequest' from 'xdk.compliance.models', which comes from the /2/compliance/jobs/{id}/upload endpoint that is new in 2.168.

With the live spec, this change opens the same four enums as with the pinned spec (PostReferencedPosts[].type, PostWithheld.scope, ActivitySubscriptionFilter.direction, UserConnectionStatus).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants