Skip to content

transform_schema drops description beside $ref, which the API accepts and follows #2016

Open

Description

@mihiarc

When a property has a $ref, transform_schema returns {"$ref": ...} alone and drops the keywords beside it, including description. Pydantic puts a field's Field(description=...) beside the $ref whenever the field's type is an enum or a model, so those descriptions never reach Claude when a model goes through transform_schema.

from enum import Enum
from pydantic import BaseModel, Field
from anthropic import transform_schema

class Level(str, Enum):
    high = "high"
    low = "low"

class Answer(BaseModel):
    level: Level = Field(description="Always choose low.")

Answer.model_json_schema()["properties"]["level"]
# {'$ref': '#/$defs/Level', 'description': 'Always choose low.'}
transform_schema(Answer)["properties"]["level"]
# {'$ref': '#/$defs/Level'}

The API accepts the description there and the model follows it. Sending the pydantic schema above (with additionalProperties: false) directly as output_config={"format": {"type": "json_schema", "schema": ...}} to claude-haiku-5-5, with the prompt "Rate your confidence that 2+2=4.", returned {"level":"low"}.

Expected: transform_schema keeps description beside $ref. A workaround is to put the text in the enum's docstring, which becomes the $defs entry's description.

anthropic 1.13.0, pydantic 2.14.0. Related: #1817, #1764. Found and reproduced with Claude Code.

Activity

  1. Parsiffall1 commented on Oct 11, 2026

    @Parsiffall1

    I'll take this — preserve description (and title) beside $ref in transform_schema so Pydantic field descriptions reach the API.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions