JSON schemas with circular references

[lord-haffi]

Initial Checks

• I have searched Google & GitHub for similar requests and couldn't find anything
• I have read and followed the docs and still think this feature is missing

Description

When using models with circular references, the generated JSON-schema (using model_json_schema) has an unexpected output (at least for me). Instead of defining the model on the root there will be an allOf present with a reference to the model in $defs. I believe it was solved this way to avoid redundance since the model must be present in $defs in order to correctly model the circular reference. However, I think this redundance sometimes can be helpful. Currently I'm modifying the result schema by myself to achieve this. I think an option for this on model_json_schema would be best. Or at least a short description in the documentation.

import json
import re
from pydantic import BaseModel

class A(BaseModel):
    b: "B"
    c: str

class B(BaseModel):
    a: A

A.model_rebuild()
result_schema = A.model_json_schema()
# result_schema = {
#   "$defs": {
#     "A": {
#       "properties": {
#         "b": {
#           "$ref": "#/$defs/B"
#         },
#         "c": {
#           "title": "C",
#           "type": "string"
#         }
#       },
#       "required": [
#         "b",
#         "c"
#       ],
#       "title": "A",
#       "type": "object"
#     },
#     "B": {
#       "properties": {
#         "a": {
#           "$ref": "#/$defs/A"
#         }
#       },
#       "required": [
#         "a"
#       ],
#       "title": "B",
#       "type": "object"
#     }
#   },
#   "allOf": [
#     {
#       "$ref": "#/$defs/A"
#     }
#   ]
# }
if {"allOf", "$defs"} == set(result_schema.keys()):
    assert (
        len(result_schema["allOf"]) == 1
    ), "Internal error: Assumed circular reference but structure is unexpected"
    # This is the case for schemas containing circular references
    reference_pattern = re.compile(r"^#/\$defs/(?P<cls_name>\w+)$")
    reference_match = reference_pattern.fullmatch(result_schema["allOf"][0]["$ref"])
    result_schema_to_merge = result_schema["$defs"][reference_match.group("cls_name")]
    del result_schema["allOf"]
    result_schema.update(result_schema_to_merge)
# result_schema = {
#   "$defs": {
#     "A": {
#       "properties": {
#         "b": {
#           "$ref": "#/$defs/B"
#         },
#         "c": {
#           "title": "C",
#           "type": "string"
#         }
#       },
#       "required": [
#         "b",
#         "c"
#       ],
#       "title": "A",
#       "type": "object"
#     },
#     "B": {
#       "properties": {
#         "a": {
#           "$ref": "#/$defs/A"
#         }
#       },
#       "required": [
#         "a"
#       ],
#       "title": "B",
#       "type": "object"
#     }
#   },
#   "properties": {
#     "b": {
#       "$ref": "#/$defs/B"
#     },
#     "c": {
#       "title": "C",
#       "type": "string"
#     }
#   },
#   "required": [
#     "b",
#     "c"
#   ],
#   "title": "A",
#   "type": "object"
# }

Affected Components

• Compatibility between releases
• Data validation/parsing
• Data serialization - .model_dump() and .model_dump_json()
• JSON Schema
• Dataclasses
• Model Config
• Field Types - adding or changing a particular data type
• Function validation decorator
• Generic Models
• Other Model behaviour - model_construct(), pickling, private attributes, ORM mode
• Plugins and integration with other tools - mypy, FastAPI, python-devtools, Hypothesis, VS Code, PyCharm, etc.

[sydney-runkle]

Hi @lord-haffi,

Thanks for your question - indeed, we simplify the schema in this way to represent the circular reference without unneeded redundancy.

Modification of the schema in the way that you're requesting seems relatively unique, so I think these changes belong in user code for now. That being said, if requests such as this one get significant traction, we could reconsider adding increased support (or at least examples for how to achieve such schema to the docs).

Closing this as not planned, based on that analysis, for now.