The Fix
pip install pydantic==2.12.0
Based on closed pydantic/pydantic issue #12232 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -131,6 +131,8 @@ class PydanticJsonSchemaWarning(UserWarning):
JsonSchemaKeyT = TypeVar('JsonSchemaKeyT', bound=Hashable)
+_PRIMITIVE_JSON_SCHEMA_TYPES = ('string', 'boolean', 'null', 'integer', 'number')
+
from pydantic import BaseModel, Field
from typing import Literal
Memory = Literal["user", "guild", "channel"]
class RememberRequest(BaseModel):
scope: Memory = Field(
description="Whether the memory is about the message author, server, or channel/group chat."
)
content: str = Field(description="The details of the memory.")
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Option A — Upgrade to fixed release\npip install pydantic==2.12.0\nWhen NOT to use: This fix is not suitable if external tools require $ref references.\n\nOption C — Workaround\nhttps://jsonref.readthedocs.io/en/latest\nWhen NOT to use: This fix is not suitable if external tools require $ref references.\n\n
Why This Fix Works in Production
- Trigger: Tell Pydantic to not generate JSON schema with $ref $defs
- Mechanism: Pydantic generates JSON schema with $ref for enums instead of inline definitions
- Why the fix works: Added a `union_format` parameter to the JSON Schema generation to control how unions are represented, allowing for inline definitions. (first fixed release: 2.12.0).
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Pydantic generates JSON schema with $ref for enums instead of inline definitions
- Production symptom (often without a traceback): Tell Pydantic to not generate JSON schema with $ref $defs
Proof / Evidence
- GitHub issue: #12232
- Fix PR: https://github.com/pydantic/pydantic/pull/12147
- First fixed release: 2.12.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.95
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.57
Verified Execution
We executed the runnable minimal repro in a temporary environment and captured exit codes + logs.
- Status: PASS
- Ran: 2026-02-11T16:52:29Z
- Package: pydantic
- Fixed: 2.12.0
- Mode: fixed_only
- Outcome: ok
Logs
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Could be a potential workaround: https://jsonref.readthedocs.io/en/latest”
“A workaround would be to replace StrEnum with Literal Yields:”
“Another use case is working with Kubernetes CRDs which unfortunately do not support $ref in the fields https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation”
“Tracking in https://github.com/pydantic/pydantic/issues/12023.”
Failure Signature (Search String)
- Tell Pydantic to not generate JSON schema with $ref $defs
- I am wondering if it is possible to disable it and use the [inline "enum"](https://json-schema.org/understanding-json-schema/reference/enum) property in JSON Schema since `$ref`
Copy-friendly signature
Failure Signature
-----------------
Tell Pydantic to not generate JSON schema with $ref $defs
I am wondering if it is possible to disable it and use the [inline "enum"](https://json-schema.org/understanding-json-schema/reference/enum) property in JSON Schema since `$ref` is seemingly unsupported on OpenAI's side.
Error Message
Signature-only (no traceback captured)
Error Message
-------------
Tell Pydantic to not generate JSON schema with $ref $defs
I am wondering if it is possible to disable it and use the [inline "enum"](https://json-schema.org/understanding-json-schema/reference/enum) property in JSON Schema since `$ref` is seemingly unsupported on OpenAI's side.
Minimal Reproduction
from pydantic import BaseModel, Field
from typing import Literal
Memory = Literal["user", "guild", "channel"]
class RememberRequest(BaseModel):
scope: Memory = Field(
description="Whether the memory is about the message author, server, or channel/group chat."
)
content: str = Field(description="The details of the memory.")
What Broke
Generated JSON schema fails to validate with OpenAI's structured JSON output.
Why It Broke
Pydantic generates JSON schema with $ref for enums instead of inline definitions
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install pydantic==2.12.0
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Option C — Workaround Temporary workaround
https://jsonref.readthedocs.io/en/latest
Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.
Fix reference: https://github.com/pydantic/pydantic/pull/12147
First fixed release: 2.12.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not suitable if external tools require $ref references.
Verify Fix
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
- Upgrade behind a canary and run integration tests against the canary before 100% rollout.
Version Compatibility Table
| Version | Status |
|---|---|
| 2.12.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.