> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions: Structured Outputs

> JSON mode, JSON schema, Pydantic integration, and provider support for structured responses

## Response Format

The chat completions API supports structured response formats, enabling you to receive consistent, predictable outputs in JSON format. This is useful for parsing responses programmatically.

### JSON Response Options

<AccordionGroup>
  <Accordion title="Basic JSON Mode: Getting Valid JSON Without Structure Constraints">
    JSON mode ensures the model's output is valid JSON without enforcing a specific structure:

    ```python theme={"dark"}
    from openai import OpenAI

    client = OpenAI(
        api_key="your_truefoundry_api_key",
        base_url="{GATEWAY_BASE_URL}"
    )

    response = client.chat.completions.create(
        model="openai-main/gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant designed to output JSON."},
            {"role": "user", "content": "Extract information about the 2020 World Series winner"}
        ],
        response_format={"type": "json_object"}
    )

    print(response.choices[0].message.content)
    ```

    **Output:**

    ```json theme={"dark"}
    {
      "team": "Los Angeles Dodgers",
      "year": 2020,
      "opponent": "Tampa Bay Rays",
      "games_played": 6,
      "series_result": "4-2"
    }
    ```
  </Accordion>

  <Accordion title="JSON Schema Mode: Enforcing Specific Data Structures">
    JSON Schema mode provides strict structure validation using predefined schemas:

    ```python theme={"dark"}
    from openai import OpenAI
    import json

    client = OpenAI(
        api_key="your_truefoundry_api_key",
        base_url="{GATEWAY_BASE_URL}"
    )

    # Define JSON schema
    user_info_schema = {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer", "minimum": 0},
            "occupation": {"type": "string"},
            "location": {"type": "string"},
            "skills": {
                "type": "array",
                "items": {"type": "string"}
            }
        },
        "required": ["name", "age", "occupation", "location", "skills"],
        "additionalProperties": False
    }

    response = client.chat.completions.create(
        model="openai-main/gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "Extract user information and respond according to the provided JSON schema."
            },
            {
                "role": "user",
                "content": "My name is Sarah Johnson, I'm 28 years old, and I work as a data scientist in New York. I'm skilled in Python, SQL, and machine learning."
            }
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "user_info",
                "schema": user_info_schema,
                "strict": True
            }
        }
    )

    # Parse response
    result = json.loads(response.choices[0].message.content)
    ```

    <Note>
      When using JSON schema with strict mode set to true, all properties defined in the schema must be included in the required array. If any property is defined but not marked as required, the API will return a 400 Bad Request Error.
    </Note>
  </Accordion>
</AccordionGroup>

### Advanced Schema Integration

<AccordionGroup>
  <Accordion title="Python Type Validation with Pydantic Models">
    Pydantic provides automatic validation, serialization, and type hints for structured data:

    ```python theme={"dark"}
    from openai import OpenAI
    from pydantic import BaseModel, Field
    from typing import List

    client = OpenAI(
        api_key="your_truefoundry_api_key",
        base_url="{GATEWAY_BASE_URL}"
    )

    # Define Pydantic model
    class UserInfo(BaseModel):
        name: str = Field(description="Full name of the user")
        age: int = Field(ge=0, description="Age in years")
        occupation: str = Field(description="Job title or profession")
        location: str = Field(description="City or location")
        skills: List[str] = Field(description="List of professional skills")

        class Config:
            extra = "forbid"  # Prevent additional fields

    response = client.chat.completions.create(
        model="openai-main/gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "Extract user information and respond according to the provided schema."
            },
            {
                "role": "user",
                "content": "Hi, I'm Mike Chen, a 32-year-old software architect from Seattle. I specialize in cloud computing, microservices, and Kubernetes."
            }
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "user_info",
                "schema": UserInfo.model_json_schema(),
                "strict": True
            }
        }
    )

    # Parse and validate with Pydantic
    user_data = UserInfo.model_validate_json(response.choices[0].message.content)
    ```

    <Note>
      When using OpenAI models with Pydantic Models, there should not be any optional fields in the pydantic model when strict mode is true. This is because the corresponding JSON schema will have missing fields in the "required" section.
    </Note>
  </Accordion>

  <Accordion title="Streamlined Pydantic Integration with OpenAI's Beta Parse API">
    The beta parse client provides the most streamlined approach for Pydantic integration:

    ```python theme={"dark"}
    from openai import OpenAI
    from pydantic import BaseModel, Field
    from typing import List, Optional

    class UserInfo(BaseModel):
        name: str = Field(description="Full name of the user")
        age: int = Field(ge=0, description="Age in years")
        occupation: str = Field(description="Job title or profession")
        location: Optional[str] = Field(None, description="City or location")
        skills: List[str] = Field(default=[], description="List of professional skills")

    client = OpenAI(
        api_key="your_truefoundry_api_key",
        base_url="{GATEWAY_BASE_URL}"
    )

    completion = client.beta.chat.completions.parse(
        model="openai-main/gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "Extract user information from the provided text."
            },
            {
                "role": "user",
                "content": "Hello, I'm Alex Rodriguez, a 29-year-old product manager from Austin. I have experience in agile methodologies, data analysis, and team leadership."
            }
        ],
        response_format=UserInfo,
    )

    user_result = completion.choices[0].message.parsed
    ```

    This approach allows for optional fields in your Pydantic model and provides a cleaner API for structured responses.
  </Accordion>
</AccordionGroup>