Implementation:Openai Openai python Shared Custom Tool Input Format

Knowledge Sources	Openai_Openai_python OpenAI API Reference
Domains	API_Types, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for defining custom tool input format as either free text or grammar-constrained provided by the openai-python SDK.

Description

CustomToolInputFormat is a TypeAlias representing a discriminated union (discriminated on the "type" field) of two possible tool input formats:

• Text - Unconstrained free-form text input with type "text".
• Grammar - A user-defined grammar with a definition string, syntax field (either "lark" or "regex"), and type "grammar".

The union uses Annotated with PropertyInfo(discriminator="type") for automatic deserialization to the correct variant based on the type field value.

Usage

Import CustomToolInputFormat when defining custom tool configurations that need to specify how tool input should be formatted or constrained.

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/types/shared/custom_tool_input_format.py

Signature

class Text(BaseModel):
    type: Literal["text"]

class Grammar(BaseModel):
    definition: str
    syntax: Literal["lark", "regex"]
    type: Literal["grammar"]

CustomToolInputFormat: TypeAlias = Annotated[
    Union[Text, Grammar], PropertyInfo(discriminator="type")
]

Import

from openai.types.shared import CustomToolInputFormat

I/O Contract

Fields (Text variant)

Name	Type	Required	Description
type	Literal["text"]	Yes	Unconstrained text format. Always "text".

Fields (Grammar variant)

Name	Type	Required	Description
definition	str	Yes	The grammar definition string.
syntax	Literal["lark", "regex"]	Yes	The syntax of the grammar definition. One of "lark" or "regex".
type	Literal["grammar"]	Yes	Grammar format. Always "grammar".

Usage Examples

from openai.types.shared.custom_tool_input_format import Text, Grammar

# Free-form text input format
text_format = Text(type="text")

# Grammar-constrained input using regex
regex_format = Grammar(
    type="grammar",
    syntax="regex",
    definition=r"\d{4}-\d{2}-\d{2}",  # Date pattern
)

# Grammar-constrained input using Lark
lark_format = Grammar(
    type="grammar",
    syntax="lark",
    definition='start: "hello" NAME\nNAME: /\\w+/',
)

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus