Struct Schema

pub struct Schema {
    pub name: Option<String>,
    pub schema: Option<JsonItem>,
    /* private fields */
}

Complete JSON schema definition with name and structure.

This is the top-level structure for defining JSON schemas that can be used with OpenAI’s structured output features. It combines a schema name with the actual schema definition to create a complete, reusable schema.

Fields

• name - A unique identifier for this schema
• schema - The actual schema definition describing the structure

Usage with OpenAI API

This structure can be directly serialized and used with OpenAI’s chat completion API to ensure structured responses that conform to the defined schema.

Example

use openai_tools::structured_output::Schema;

// Create a schema for extracting contact information
let mut contact_schema = Schema::chat_json_schema("contact_info".to_string());

contact_schema.add_property(
    "name".to_string(),
    "string".to_string(),
    Some("Full name of the person".to_string())
);
contact_schema.add_property(
    "email".to_string(),
    "string".to_string(),
    Some("Email address".to_string())
);
contact_schema.add_property(
    "phone".to_string(),
    "string".to_string(),
    Some("Phone number".to_string())
);

// Serialize for API use
let json_string = serde_json::to_string(&contact_schema).unwrap();

Fields

name: Option<String>

schema: Option<JsonItem>

Implementations

impl Schema

pub fn responses_text_schema() -> Self

Creates a new JsonSchema with the specified name.

This creates an empty object schema that can be populated with properties using the various add_* methods.

Arguments

• name - A unique identifier for this schema

Returns

A new JsonSchema instance with an empty object schema.

Example

use openai_tools::structured_output::Schema;

let schema = Schema::chat_json_schema("user_profile".to_string());
// Schema is now ready for property addition

pub fn responses_json_schema(name: String) -> Self

Creates a new JsonSchema with the specified name (alternative constructor).

This method is functionally identical to new() but provides an alternative naming convention for schema creation.

Arguments

• name - A unique identifier for this schema

Returns

A new JsonSchema instance with an empty object schema.

pub fn chat_json_schema(name: String) -> Self

Creates a new JsonSchema for chat completions with the specified name.

This method creates a schema specifically designed for use with OpenAI’s chat completion API. Unlike responses_json_schema(), this method doesn’t set a type name, making it suitable for chat-based structured outputs.

Arguments

• name - A unique identifier for this schema

Returns

A new JsonSchema instance with an empty object schema optimized for chat completions.

Example

use openai_tools::structured_output::Schema;

let mut chat_schema = Schema::chat_json_schema("chat_response".to_string());
chat_schema.add_property(
    "response".to_string(),
    "string".to_string(),
    Some("The AI's response message".to_string())
);

pub fn add_property( &mut self, prop_name: String, type_name: String, description: Option<String>, )

Adds a simple property to the schema.

This method adds a property with a basic type (string, number, boolean, etc.) to the schema. The property is automatically marked as required.

Arguments

• prop_name - The name of the property
• type_name - The JSON type (e.g., “string”, “number”, “boolean”)
• description - Optional description explaining the property’s purpose

Example

use openai_tools::structured_output::Schema;

let mut schema = Schema::chat_json_schema("person".to_string());

// Add string property with description
schema.add_property(
    "name".to_string(),
    "string".to_string(),
    Some("The person's full name".to_string())
);

// Add number property without description
schema.add_property(
    "age".to_string(),
    "number".to_string(),
    None
);

// Add boolean property
schema.add_property(
    "is_active".to_string(),
    "boolean".to_string(),
    Some("Whether the person is currently active".to_string())
);

pub fn add_array(&mut self, prop_name: String, items: Vec<(String, String)>)

Adds an array property with string elements to the schema.

This method creates an array property where each element is an object with string properties. All specified properties in the array elements are marked as required.

Arguments

• prop_name - The name of the array property
• items - Vector of (property_name, description) tuples for array elements

Example

use openai_tools::structured_output::Schema;

let mut schema = Schema::chat_json_schema("user_profile".to_string());

// Add an array of address objects
schema.add_array(
    "addresses".to_string(),
    vec![
        ("street".to_string(), "Street address".to_string()),
        ("city".to_string(), "City name".to_string()),
        ("state".to_string(), "State or province".to_string()),
        ("zip_code".to_string(), "Postal code".to_string()),
    ]
);

// This creates an array where each element must have all four properties

Note

Currently, this method only supports arrays of objects with string properties. For more complex array structures, you may need to manually construct the schema using JsonItem and ItemType.

pub fn clone(&self) -> Self

Creates a deep clone of this JsonSchema instance.

This method performs a deep copy of the entire schema structure, including all nested properties and their definitions.

Returns

A new JsonSchema instance that is an exact copy of this one.

Example

use openai_tools::structured_output::Schema;

let mut original = Schema::chat_json_schema("template".to_string());
original.add_property("id".to_string(), "number".to_string(), None);

let mut copy = original.clone();
copy.add_property("name".to_string(), "string".to_string(), None);

// original still only has "id", copy has both "id" and "name"

Trait Implementations

impl Clone for Schema

fn clone(&self) -> Schema

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Schema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Schema

fn default() -> Schema

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Schema

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Schema

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.