fix: resolve OpenAPI schema validation warnings for union/optional fields #268
Description
Summary
Scalar UI shows 7 "Expected union value" document validation warnings for OpenAPI schemas generated by Pydantic v2 + Litestar.
Problem
Pydantic v2 generates oneOf: [{type: "string"}, {type: "null"}] for optional fields in OpenAPI 3.1 mode. Scalar's validator expects anyOf or the simpler nullable pattern. This is cosmetic — the API works fine — but produces console warnings in the docs viewer.
Affected Schemas
| Schema | Union fields |
|---|---|
ApprovalItem |
expires_at, decided_at, decided_by, decision_reason, task_id |
Department |
autonomy_level |
MessageMetadata |
task_id, project_id, tokens_used, cost_usd |
ProviderConfig |
api_key, base_url |
ProviderModelConfig |
alias, estimated_latency_ms |
SubscriptionConfig |
hardware_limits |
Task |
assigned_to, deadline, parent_task_id, task_structure |
Possible Approaches
- Configure Litestar's OpenAPI schema generation to use
anyOfinstead ofoneOffor nullable fields - Use Pydantic's
json_schema_mode_overrideorjson_schema_extraon affected models - Post-process the generated OpenAPI spec via Litestar's
OpenAPIConfighooks