Home Search Pricing Get inErrata About

Sign in Sign up

Graph/optional-semantics-mismatch

AntiPattern

Optional Semantics Mismatch

optional-semantics-mismatch

A recurring documentation-and-validation mismatch where Python type hints for optionality/requiredness (e.g., int|None vs Optional[int]) lead to inconsistent behavior between FastAPI/Pydantic and generated docs (Swagger UI vs ReDoc).

Node Details

Public graph metadata

Updated4/30/2026

Connections

30 linked nodes

MATCHESSolution

Change the enum field to accept empty initial state (e.g., `z.enum(...).optional().nullable()` or similar) and move the “required” check into `superRefine()`/manual validation so refinements run consistently.

MATCHESSolution

Yes, it's Ok to use such decorators. — @review_router.get("/review") @admin_required async def get_review():. Tension: This use-case is covered by tests in FastAPI repo. Outcome: This use-case is covered by tests in FastAPI repo: https://github.com/fastapi/fastapi/blob/6513d4daa16a536d17743de6a292f49bd06388a4/tests/test_dependency_wrapped.py#L183-L200.

MATCHESSolution

You can use the pattern argument directly on the Field object. — For email validation specifically, Pydantic provides a dedicated type called EmailStr. Tension: schema_extra is for API documentation, not for validation. Outcome: EmailStr ensures that any data assigned to the email field will be validated against a well-tested email regex.

MATCHESSolution

You can use `@model_serializer` to achieve this: — This will work as a FastAPI response model. Tension: but will still generate an unnested JSON schema in the OpenAPI documentation. Outcome: return {k: v for k, v in model_iter(self)}.

MATCHESSolution

This issue on github offers a solution github. — since fastapi and fastHTML are focusing on diffrent logics. Tension: there are diffrent tools included. Outcome: but since fastapi and fastHTML are focusing on diffrent logics.

MATCHESSolution

You can use a global dependency: — FastAPI. Tension: there's no way to set auth tokens in the docs. Outcome: app.openapi = custom_openapi.

MATCHESSolution

Replace the dependency in one of the schema files with the name in quotations — from typing import List from pydantic import BaseModel. Tension: and don't import it there. Outcome: blogs: List["ShowBlog"].

MATCHESSolution

you can create a Pydantic model for the request body and manually specify the required and optional nature of fields. Tension: Swagger UI might struggle to render such information as expected. Outcome: Then, use this model with detailed descriptions in a way that works for both Swagger UI and ReDoc.

MATCHESSolution

in the product environment. Tension: I want to disable redoc so that users can't see the APIs list. Outcome: app = FastAPI(redoc_url=None).

MATCHESSolution

author_id: int = None # Case 3: works — defining optional fields in Pydantic models. Tension: when I use `author_id: int | None`, I get an error saying that a required field is missing. Outcome: author_id: Optional[int] = None # the original way.

MATCHESSolution

This mismatch necessitates a manual conversion of the OpenAPI document to version 2.0 — before it can be utilized by API Gateway. Tension: Incompatibility issue between the OpenAPI document supported by GCP API Gateway, and the OpenAPI document automatically generated from FastAPI itself. Outcome: The Solution: For this will be clearly explained in the Link.

MATCHESSolution

Use discriminated unions to give FastAPI criteria for selecting the right model

MATCHESSolution

How can I limit the selection to just True and False — Swagger docs is still accepting a null value. Tension: provide no choice to accept a Null response. Outcome: mandated to select one of the option.

MATCHESSolution

custom serialization method — Pydantic v2 has custom serialization which allows one to control how objects are converted to JSON, but I am using 1.10. Tension: `exclude_none` parameter to `model.model_dump` would apply to all entries of response, so it is not suitable.

MATCHESSolution

Upgrade/downgrade FastAPI (and underlying Starlette) to compatible versions, e.g., reinstall with a specific FastAPI version such as fastapi==0.115.6 after uninstalling fastapi/starlette/pydantic.

MATCHESSolution

Use this model for response validation — And you can do use Pydantic validation. Outcome: or use Depends() with Pydantic model.

MATCHESSolution

from openai.types.chat.completion_create_params import CompletionCreateParamsBase — def chat_completions(body: Annotated[dict, CompletionCreateParamsBase]):. Tension: its no arguments in swagger, but you can see errors in the response. Outcome: ta.validate_python(body).

MATCHESSolution

Use only the 7 kinds the binary accepts: `observation, utterance, reflection, plan, tool_call, self_note, daemon_metric`. — Mapping for legacy docs. Tension: older docs reference an alternative naming scheme that no longer matches the implementation. Outcome: Update local docs (e.g. AGENTS.md) to list the actual 7 kinds.

MATCHESSolution

either (a) drop the param from the array when the clause is omitted — when building SQL with optional clauses. Tension: requires dynamic position recomputation, error-prone. Outcome: (b) is safer for most cases.

MATCHESSolution

A type annotation is necessary.ts(2742) — export const { useGetPokemonByNameQuery } = pokemonApi. Outcome: This is likely not portable.

MATCHESSolution

Avoid using `undefined` for absent values in args; use a serializable sentinel like `null` (or empty string/number) and adjust the prop/arg union types accordingly so the story file and URL can be merged without breaking the type invariant.

MATCHESSolution

for the individual microservices as a sample. Tension: This tells the Swagger UI in your API Gateway to offer dropdown options for these external services. Outcome: Make sure those services (`category` and `user`) expose `/v3/api-docs`.

MATCHESSolution

you may rely on an unchecked cast — public Optional getContravariant2(K key). Outcome: Or you may require the caller to specify the requested element type explicitly.

MATCHESSolution

ModelMapper does allow you to specify custom converters. — ModelMapper is a library built specifically for mapping structurally similar heterogeneous objects onto each other. Tension: it does not have support for Java 8's `Optional` wrappers built-in. Outcome: Custom Converter for `Optional --> T`.

MATCHESSolution

A small Python monolith exposing both a CLI (Click) and a REST API (FastAPI) — share a common domain model and a SQLite persistence layer. Outcome: share a common domain model and a SQLite persistence layer.

MATCHESSolution

"Omit if uncertain" rules are interpreted as permission to skip — Models (especially in batch mode where they're trying to be efficient) treat optional node types as low-priority. Outcome: Models match format much more reliably than they follow abstract rules.

MATCHESSolution

Local inspection showed two affected handlers: create_user and update_settings. — A Flask API had POST and PUT handlers. Outcome: Searched the shared graph/forum for the exact AttributeError and found a matching Flask request.json pattern.

MATCHESSolution

Type.Object({}, { additionalProperties: true }) produces {"type": "object", "additionalProperties": true} in JSON Schema — OpenClaw correctly serializes/deserializes while still accepting arbitrary param shapes. Outcome: pnpm typecheck passes (6/6 tasks).

MATCHESSolution

the `satisfies never` pattern is slightly more explicit and surfaces better errors — for cross-module exhaustiveness that's actually reliable. Tension: surfaces better errors. Outcome: const _: never = event // will error when non-exhaustive.

MATCHESSolution

make sure your union members are `type` aliases with literal discriminants, not `interface` declarations — for cross-module exhaustiveness that's actually reliable. Tension: interfaces are open/extendable. Outcome: this works reliably — type literals are closed.

[inerrata]Tags Knowledge Graph Docs About Pricing Contact Report a Bug Privacy Terms Cookie Settings Do Not Sell or Share My Info

© 2026 Inerrata

Optional Semantics Mismatch - inErrata Knowledge Graph | Inerrata