How to beginner · 3 min read

How to write JSON schema for function calling

Quick answer

To write a JSON schema for function calling, define the function's name, description, and a parameters object following JSON Schema standards, specifying type, properties, and required fields. This schema enables the AI to understand the function signature and arguments for precise tool invocation.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official openai Python SDK version 1.0 or higher and set your API key as an environment variable.

bash

pip install openai>=1.0

export OPENAI_API_KEY="your_api_key_here"  # Linux/macOS
setx OPENAI_API_KEY "your_api_key_here"  # Windows PowerShell

output

Collecting openai
  Downloading openai-1.x.x-py3-none-any.whl (xx kB)
Installing collected packages: openai
Successfully installed openai-1.x.x

# No output for environment variable set

Step by step

Define a JSON schema for your function's parameters using the tools parameter in the chat.completions.create call. The schema must follow JSON Schema standards with type, properties, and required fields.

python

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Define the function schema
function_tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City and state, e.g., San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

messages = [
    {"role": "user", "content": "What's the weather in New York City?"}
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=function_tools
)

print("Response:", response.choices[0].message.content)

# Check if the model wants to call the function
if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print("Function call arguments:", args)

output

Response: The current weather in New York City is 72°F and sunny.
Function call arguments: {'location': 'New York City'}

Common variations

You can define multiple functions by adding more entries to the tools list. Use different type constraints like integer, boolean, or nested object properties. Async calls and streaming responses are supported by the OpenAI SDK but do not affect the JSON schema format.

python

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Multiple function schemas
function_tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "set_alarm",
            "description": "Set an alarm at a specific time",
            "parameters": {
                "type": "object",
                "properties": {
                    "time": {"type": "string", "description": "Time in HH:MM format"},
                    "label": {"type": "string"}
                },
                "required": ["time"]
            }
        }
    }
]

messages = [{"role": "user", "content": "Set an alarm for 7:30 AM"}]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=function_tools
)

print("Response:", response.choices[0].message.content)

if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print("Function call arguments:", args)

output

Response: Setting an alarm for 7:30 AM.
Function call arguments: {'time': '7:30', 'label': ''}

Troubleshooting

If the AI does not recognize your function schema, verify that the tools parameter is correctly formatted and passed to chat.completions.create.
Ensure all required properties are listed in the required array.
Use valid JSON Schema types and enums to avoid schema validation errors.
If finish_reason is not tool_calls, the model did not invoke the function; adjust your prompt or schema accordingly.

✅

Key Takeaways

Use the tools parameter with a JSON schema to define function calling in OpenAI chat completions.
The JSON schema must include type, properties, and required fields for parameters.
Check finish_reason for tool_calls to detect when the model wants to invoke a function.
You can define multiple functions with distinct schemas in the tools list.
Validate your JSON schema carefully to avoid errors and ensure the AI understands your function signature.

Verified 2026-04 · gpt-4o-mini

Verify ↗