SkipJsonSchema nested models appear in OpenAPI schema #14651

cemsozens · 2026-01-05T20:23:57Z

cemsozens
Jan 5, 2026

First Check

I added a very descriptive title here.
I used the GitHub search to find a similar question and didn't find it.
I searched the FastAPI documentation, with the integrated search.
I already searched in Google "How to X in FastAPI" and didn't find any information.
I already read and followed all the tutorial in the docs and didn't find an answer.
I already checked if it is not related to FastAPI but to Pydantic.
I already checked if it is not related to FastAPI but to Swagger UI.
I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

I commit to help with one of those options 👆

Example Code

from datetime import datetime
from fastapi import FastAPI
from pydantic import BaseModel, Field
from pydantic.json_schema import SkipJsonSchema

app = FastAPI()


# --- Models ---

class NestedTestModel(BaseModel):
    """A nested model that will be hidden via SkipJsonSchema."""
    field_a: str
    field_b: int
    field_c: float | None = None


class AnotherNestedModel(BaseModel):
    """Another nested model to hide."""
    key: str
    value: str
    timestamp: datetime | None = None


class TestModel(BaseModel):
    """
    Main model demonstrating SkipJsonSchema with nested models.
    Only `name` and `value` appear in the OpenAPI schema.
    """
    name: str
    value: int
    
    # Entire nested models hidden from schema
    hidden_nested: SkipJsonSchema[NestedTestModel | None] = None
    hidden_another: SkipJsonSchema[AnotherNestedModel | None] = None
    hidden_dict: SkipJsonSchema[dict[str, float]] = Field(default_factory=dict)
    hidden_list: SkipJsonSchema[list[str]] = Field(default_factory=list)


# --- Endpoints ---

@app.post("/test/", response_model=TestModel)
def create_test(item: TestModel):
    """
    Create test item. The nested models and collections
    (hidden_nested, hidden_another, hidden_dict, hidden_list)
    are all hidden from the OpenAPI schema.
    """
    # Server sets hidden fields
    item.hidden_nested = NestedTestModel(
        field_a="test",
        field_b=42,
        field_c=3.14,
    )
    item.hidden_another = AnotherNestedModel(
        key="sample",
        value="data",
        timestamp=datetime.now(),
    )
    item.hidden_dict = {"score": 0.95}
    item.hidden_list = ["tag1", "tag2"]
    return item

Description

NestedTestModel and AnotherNestedModel appear in openapi.yml file even there are used with SkipJsonSchema under another model. This is not the case in 0.118.0.

openapi file in 0.128.0:

openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
paths:
  /test/:
    post:
      summary: Create Test
      description: 'Create test item. The nested models and collections

        (hidden_nested, hidden_another, hidden_dict, hidden_list)

        are all hidden from the OpenAPI schema.'
      operationId: create_test_test__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AnotherNestedModel:
      properties:
        key:
          type: string
          title: Key
        value:
          type: string
          title: Value
        timestamp:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Timestamp
      type: object
      required:
      - key
      - value
      title: AnotherNestedModel
      description: Another nested model to hide.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    NestedTestModel:
      properties:
        field_a:
          type: string
          title: Field A
        field_b:
          type: integer
          title: Field B
        field_c:
          anyOf:
          - type: number
          - type: 'null'
          title: Field C
      type: object
      required:
      - field_a
      - field_b
      title: NestedTestModel
      description: A nested model that will be hidden via SkipJsonSchema.
    TestModel:
      properties:
        name:
          type: string
          title: Name
        value:
          type: integer
          title: Value
      type: object
      required:
      - name
      - value
      title: TestModel
      description: 'Main model demonstrating SkipJsonSchema with nested models.

        Only `name` and `value` appear in the OpenAPI schema.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError

openapi file with 0.118.0

openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
paths:
  /test/:
    post:
      summary: Create Test
      description: 'Create test item. The nested models and collections

        (hidden_nested, hidden_another, hidden_dict, hidden_list)

        are all hidden from the OpenAPI schema.'
      operationId: create_test_test__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TestModel:
      properties:
        name:
          type: string
          title: Name
        value:
          type: integer
          title: Value
      type: object
      required:
      - name
      - value
      title: TestModel
      description: 'Main model demonstrating SkipJsonSchema with nested models.

        Only `name` and `value` appear in the OpenAPI schema.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.128.0

Pydantic Version

2.12.5

Python Version

3.13.1

Additional Context

No response

YuriiMotov · 2026-01-06T20:25:12Z

YuriiMotov Jan 6, 2026
Collaborator

This is a known behavior in FastAPI/Pydantic.

Could you please provide links where it was previously discussed?

YuriiMotov · 2026-01-06T20:27:09Z

YuriiMotov
Jan 6, 2026
Collaborator

Looks somewhat similar to #14252

I will investigate it later when I have time

0 replies

sk- · 2026-01-08T00:37:05Z

sk-
Jan 8, 2026

@garg-khushi note that in the OP the models being included in the openapi spec are exactly those that have SkipJsonSchema and none of those models have nested schemas.

Please also note that this used to work with Fastapi 0.118 and stopped working with Fastapi 0.119. The issues is unrelated to pydantic as in the OP the same pydantic version was used.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

SkipJsonSchema nested models appear in OpenAPI schema #14651

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments 1 reply

This comment was marked as spam.

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

SkipJsonSchema nested models appear in OpenAPI schema #14651

Uh oh!

cemsozens Jan 5, 2026

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

FastAPI Version

Pydantic Version

Python Version

Additional Context

Replies: 3 comments · 1 reply

This comment was marked as spam.

Uh oh!

YuriiMotov Jan 6, 2026 Collaborator

Uh oh!

YuriiMotov Jan 6, 2026 Collaborator

Uh oh!

sk- Jan 8, 2026

cemsozens
Jan 5, 2026

Replies: 3 comments 1 reply

YuriiMotov Jan 6, 2026
Collaborator

YuriiMotov
Jan 6, 2026
Collaborator

sk-
Jan 8, 2026