Implementation:Guardrails ai Guardrails Pydantic Utils

Knowledge Sources	Guardrails
Domains	Utilities, Schema Conversion
Last Updated	2026-02-14 00:00 GMT

Overview

Provides a utility function to convert Pydantic BaseModel classes into OpenAI function-calling parameter dictionaries.

Description

The Pydantic Utils module contains the convert_pydantic_model_to_openai_fn function, which bridges Pydantic model definitions and OpenAI's function-calling API format. The function performs the following steps:

1. Accepts a Pydantic BaseModel type or a List[BaseModel] generic type.
2. If the input is a List type, it extracts the inner item type and validates that exactly one child type is specified.
3. Calls model_json_schema() on the Pydantic model to generate a JSON Schema representation.
4. Sets the schema title to the model class name.
5. If the input was a list type, wraps the schema in an array JSON Schema with the title Array<ModelName>.
6. Constructs and returns an OpenAI function parameters dictionary with name, parameters, and optionally description fields.

This utility is part of the pipeline for converting Guardrails output schemas into formats compatible with OpenAI's structured output capabilities.

Usage

Use this function when you need to convert a Pydantic model definition into an OpenAI function-calling parameter dictionary. This is typically used internally by Guardrails when preparing function call specifications for LLM integrations that support structured output via function/tool calling.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/utils/pydantic_utils.py

Signature

def convert_pydantic_model_to_openai_fn(
    model: Union[Type[BaseModel], Type[List[Type[BaseModel]]]],
) -> Dict: ...

Import

from guardrails.utils.pydantic_utils import convert_pydantic_model_to_openai_fn

I/O Contract

Input

Parameter	Type	Description
model	Union[Type[BaseModel], Type[List[Type[BaseModel]]]]	A Pydantic BaseModel class or a List[BaseModel] generic type

Output

Key	Type	Description
name	str	The model class name (or Array<ClassName> for list types)
parameters	dict	The JSON Schema generated from the Pydantic model
description	str (optional)	Present only if the JSON Schema includes a description field

Returns: Dict -- An OpenAI function parameters dictionary.

Raises:

• ValueError -- If a List type has more than one child type argument

Usage Examples

from pydantic import BaseModel
from guardrails.utils.pydantic_utils import convert_pydantic_model_to_openai_fn

class Person(BaseModel):
    """A person with a name and age."""
    name: str
    age: int

# Convert a single model
fn_params = convert_pydantic_model_to_openai_fn(Person)
# Result:
# {
#     "name": "Person",
#     "description": "A person with a name and age.",
#     "parameters": {
#         "title": "Person",
#         "description": "A person with a name and age.",
#         "type": "object",
#         "properties": {
#             "name": {"title": "Name", "type": "string"},
#             "age": {"title": "Age", "type": "integer"},
#         },
#         "required": ["name", "age"],
#     },
# }

from typing import List
from pydantic import BaseModel
from guardrails.utils.pydantic_utils import convert_pydantic_model_to_openai_fn

class Item(BaseModel):
    label: str
    value: float

# Convert a list model
fn_params = convert_pydantic_model_to_openai_fn(List[Item])
# Result:
# {
#     "name": "Array<Item>",
#     "parameters": {
#         "title": "Array<Item>",
#         "type": "array",
#         "items": { ... Item schema ... },
#     },
# }

Related Pages

• Guardrails_ai_Guardrails_Guard -- Uses converted schemas for OpenAI function-calling integration
• Guardrails_ai_Guardrails_RailTypes -- Defines the type system that Pydantic models map to