openai/openai-python · error · TypeError

Expected {json_schema} to be a dictionary; path={path}

Error message

Expected {json_schema} to be a dictionary; path={path}

What it means

_ensure_strict_json_schema recursively walks a JSON schema and mutates it to conform to the API's strict mode. Every node (including $defs entries) must be a JSON object/dict; encountering a non-dict node (e.g. a list or string where an object is expected) raises this TypeError with the path where it failed.

Source

Thrown at src/openai/lib/_pydantic.py:37

    elif (not PYDANTIC_V1) and isinstance(model, pydantic.TypeAdapter):
        schema = model.json_schema()
    else:
        raise TypeError(f"Non BaseModel types are only supported with Pydantic v2 - {model}")

    return _ensure_strict_json_schema(schema, path=(), root=schema)


def _ensure_strict_json_schema(
    json_schema: object,
    *,
    path: tuple[str, ...],
    root: dict[str, object],
) -> dict[str, Any]:
    """Mutates the given JSON schema to ensure it conforms to the `strict` standard
    that the API expects.
    """
    if not is_dict(json_schema):
        raise TypeError(f"Expected {json_schema} to be a dictionary; path={path}")

    defs = json_schema.get("$defs")
    if is_dict(defs):
        for def_name, def_schema in defs.items():
            _ensure_strict_json_schema(def_schema, path=(*path, "$defs", def_name), root=root)

    definitions = json_schema.get("definitions")
    if is_dict(definitions):
        for definition_name, definition_schema in definitions.items():
            _ensure_strict_json_schema(definition_schema, path=(*path, "definitions", definition_name), root=root)

    typ = json_schema.get("type")
    if typ == "object" and "additionalProperties" not in json_schema:
        json_schema["additionalProperties"] = False

    # object types
    # { 'type': 'object', 'properties': { 'a':  {...} } }
    properties = json_schema.get("properties")

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Simplify the model: replace exotic/custom types with plain annotated types and regenerate
2. Upgrade to pydantic v2 latest, then retest the model's model_json_schema() output
3. Isolate the offending field by bisecting the model and inspecting model_json_schema() output at the failing path

Example fix

# before
class Output(BaseModel):
    class Config:
        json_schema_extra = lambda schema: schema.update(items=[])  # corrupts schema
# after
class Output(BaseModel):
    items: list[int]

schema = Output.model_json_schema()
import json; json.dumps(schema)  # smoke-test serializability
# inspect nodes: every dict/def entry should be an object

try:
    strict = to_strict_json_schema(Output)
except TypeError as e:
    raise ValueError(f"model {Output} produces a non-strict-compatible schema: {e}") from e

When it happens

Trigger: A pydantic model whose generated JSON schema has a malformed node — typically caused by custom json_schema serializers, union weirdness, or hand-built TypeAdapters over non-schema types; also pydantic v1 generating differently-shaped schemas.

Common situations: Exotic pydantic field types or custom schema serializers; pydantic v1 environments; models using Any or untyped dict fields that emit non-object subschemas.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Non BaseModel types are only supported with Pydantic v2 - {m
• Expected `$ref: {ref}` to resolved to a dictionary but got {
• Value is not iterable
• Expected Content-Type response header to be `application/jso
• Unexpected $ref format {ref!r}; Does not start with #/

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/5a1adde76e04354b. Report an issue: GitHub.