Repository navigation
Conversation
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>
|
A note on CI, since it generates from the live spec (
With the live spec, this change opens the same four enums as with the pinned spec ( |
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 returnsreferenced_posts[].type == "reposted", and any timeline page that contains a repost fails:The published spec (
https://api.x.com/2/openapi.json,info.version2.168, and the pinnedspecs/openapi.json2.167) still lists onlyretweeted | quoted | replied_toforPostReferencedPosts.items.type. Reported in xdevplatform/xdk-python#7.Change
Enums inside component schemas that an operation response can reach become open enums:
Literal["retweeted", "quoted", "replied_to"]Union[Literal["retweeted", "quoted", "replied_to"], str]"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_moduleandts_schema_declarationstake that set and mark enums in those schemas as open (x-xdk-open-enum). Everything else is unchanged:py_type/ts_type, which never open enums. For example,post_fields: Optional[List[Literal["article", "article_title", ...]]]inxdk/lists/client.py(andpostFields?: Array<"article" | ...>in TS) is unchanged.CreatePostsRequest,MediaUploadRequest,CreateComplianceJobsRequest, ...) keepLiterals.Problemis aoneOfdiscriminated on single-valuetypeURIs, and opening those would break TS narrowing and let pydantic's smart-mode union pick the wrong*Problemclass.With the pinned spec, exactly four fields change, in both SDKs'
schemasmodules:PostReferencedPosts[].type,PostWithheld.scope,ActivitySubscriptionFilter.directionandUserConnectionStatus. Per-tag models and clients are unchanged, aside from the existing run-to-run operation-order nondeterminism.Tests
xdk-libunit tests: open enums in both languages, strict enums outside the set and viapy_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 -- --checkandcargo clippy --all --all-targets --all-features -- -D warnings: clean.specs/openapi.json): 1276/1276 passed, the same as before.tsc --noEmit, and 1178/1178 tests passed, the same as before.GetPostsResponsepage with{"id": "1", "type": "reposted"}fails before and validates after."quoted"still validates. A non-stringtypeis still rejected.GetPostsResponseliteral withtype: 'reposted'failstscbefore and compiles after.postFields: ['not_a_field']is still a type error.Notes / open questions
repostedshould be added toPostReferencedPosts.items.type. This PR stops a spec lag from breaking every page; it doesn't replace fixing the spec.| (string & {}),t === "quoted"no longer narrowstto the literal, and a typo in a comparison isn't caught. That is inherent to any open type. Mypy also collapsesUnion[Literal[...], str]tostr, while pyright/Pylance keep the literals.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.Problemtypes inerrorswould 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