Schema: Fluent JSON Schema Builder for Tools and Output

Schema is a single, fluent class that covers all JSON Schema node types. Rather than a hierarchy of per-type classes, it uses static factory methods to create typed nodes and chainable modifier methods to apply constraints. A Schema instance can describe a primitive value, an array, an object with nested properties, or an enumerated string — and can convert itself to a provider-ready JSON Schema array via jsonSchema().

Constants

Constant	Value
`Schema::TYPE_STRING`	`'string'`
`Schema::TYPE_INTEGER`	`'integer'`
`Schema::TYPE_NUMBER`	`'number'`
`Schema::TYPE_BOOLEAN`	`'boolean'`
`Schema::TYPE_ARRAY`	`'array'`
`Schema::TYPE_OBJECT`	`'object'`
`Schema::TYPE_NULL`	`'null'`

Factory methods

`string()`

Create a string schema node.

public static function string(?string $name = null, ?string $description = null): self

name

string | null

default:"null"

The property name used when this schema is nested inside an object or tool input.

description

string | null

default:"null"

Human-readable description forwarded into the JSON Schema description field.

$schema = Schema::string('city', 'The city name to look up');

`integer()`

Create an integer schema node.

public static function integer(?string $name = null, ?string $description = null): self

name

string | null

default:"null"

Property name for use inside an object.

description

string | null

default:"null"

Human-readable description.

$schema = Schema::integer('page', 'Page number (1-indexed)');

`number()`

Create a floating-point number schema node.

public static function number(?string $name = null, ?string $description = null): self

name

string | null

default:"null"

Property name for use inside an object.

description

string | null

default:"null"

Human-readable description.

$schema = Schema::number('score', 'Relevance score between 0.0 and 1.0');

`boolean()`

Create a boolean schema node.

public static function boolean(?string $name = null, ?string $description = null): self

name

string | null

default:"null"

Property name for use inside an object.

description

string | null

default:"null"

Human-readable description.

$schema = Schema::boolean('is_active', 'Whether the item is currently active');

`array()`

Create an array schema node whose items match a given inner schema.

public static function array(self $items, ?string $name = null, ?string $description = null): self

items

Schema

required

The schema that every element in the array must conform to.

name

string | null

default:"null"

Property name for use inside an object.

description

string | null

default:"null"

Human-readable description.

// Array of strings
$tags = Schema::array(Schema::string(), 'tags', 'List of tag strings');

// Array of objects
$addresses = Schema::array(
    Schema::object('address', properties: [
        Schema::string('street')->required(),
        Schema::string('city')->required(),
    ]),
    'addresses',
    'List of postal addresses',
);

`object()`

Create an object schema node with named properties.

public static function object(string $name, ?string $description = null, array $properties = []): self

name

string

required

The name of this object schema. Required and must be non-empty.

description

string | null

default:"null"

Human-readable description of this object.

properties

Schema[]

default:"[]"

An indexed array of named Schema instances. Each property must have a non-empty name. Throws InvalidArgumentException if any property is unnamed or is not a Schema instance.

$personSchema = Schema::object('person', 'A person record', [
    Schema::string('name', 'Full name')->required(),
    Schema::integer('age', 'Age in years')->required(),
    Schema::string('email', 'Email address')->nullable(),
]);

`enum()`

Create an enumerated string schema that constrains values to a fixed list.

public static function enum(array $values, ?string $name = null, ?string $description = null): self

values

string[]

required

A non-empty list of allowed string values. Throws InvalidArgumentException when empty.

name

string | null

default:"null"

Property name for use inside an object.

description

string | null

default:"null"

Human-readable description.

$status = Schema::enum(['pending', 'active', 'archived'], 'status', 'Record lifecycle status');

Modifiers

`required()`

Mark this schema node as required when it is a property of an object. Returns a new instance (the original is not mutated).

public function required(): self

$name = Schema::string('name', 'Full name')->required();

`nullable()`

Allow this schema to also accept null values. In the generated JSON Schema, the type becomes an array [originalType, 'null']. Returns a new instance.

public function nullable(): self

$middleName = Schema::string('middle_name', 'Middle name')->nullable();

Accessors

`name()`

Return the name assigned to this schema node.

public function name(): ?string

return

string | null

The schema node’s name, or null if none was given.

$schema = Schema::string('city');
echo $schema->name(); // "city"

`description()`

Return the description string, if one was set.

public function description(): ?string

return

string | null

The description text, or null.

$schema = Schema::string('city', 'The city name');
echo $schema->description(); // "The city name"

`type()`

Return the JSON Schema type string for this node.

public function type(): string

return

string

One of the TYPE_* constants, e.g. 'string', 'integer', 'object', 'array'.

$schema = Schema::integer('count');
echo $schema->type(); // "integer"

`isRequired()`

Return whether this schema has been marked as required.

public function isRequired(): bool

return

bool

true if required() was called on this node.

$schema = Schema::string('name')->required();
var_dump($schema->isRequired()); // bool(true)

`isNullable()`

Return whether this schema permits null values.

public function isNullable(): bool

return

bool

true if nullable() was called on this node.

$schema = Schema::string('nickname')->nullable();
var_dump($schema->isNullable()); // bool(true)

`items()`

Return the inner item schema for array nodes.

public function items(): ?self

return

Schema | null

The schema describing each array element, or null if this is not an array node.

$arr = Schema::array(Schema::string(), 'tags');
$items = $arr->items(); // Schema::string()

`properties()`

Return the named property schemas for object nodes, keyed by name.

public function properties(): array

return

array<string, Schema>

An associative array mapping property names to their Schema instances. Returns an empty array for non-object nodes.

$obj = Schema::object('user', properties: [
    Schema::string('name')->required(),
    Schema::integer('age'),
]);

foreach ($obj->properties() as $name => $prop) {
    echo "{$name}: {$prop->type()}\n";
}
// name: string
// age: integer

`enumValues()`

Return the list of allowed enum values, or null for non-enum nodes.

public function enumValues(): ?array

return

array | null

An indexed array of allowed string values, or null if this node is not an enum.

$schema = Schema::enum(['asc', 'desc'], 'order');
var_dump($schema->enumValues()); // ['asc', 'desc']

`jsonSchema()`

Convert this schema node into a plain PHP array representing a JSON Schema document. This is the format passed to AI providers.

public function jsonSchema(): array

return

array<string, mixed>

A JSON Schema-compatible associative array. Object schemas include properties, required field lists, and additionalProperties: false. Nullable schemas use an array type. Array schemas include an items key.

$schema = Schema::object('address', 'A mailing address', [
    Schema::string('street', 'Street line')->required(),
    Schema::string('city', 'City name')->required(),
    Schema::string('postcode')->nullable(),
]);

print_r($schema->jsonSchema());
/*
[
  'type'                 => 'object',
  'title'                => 'address',
  'description'          => 'A mailing address',
  'properties'           => [
    'street'   => ['type' => 'string', 'title' => 'street', 'description' => 'Street line'],
    'city'     => ['type' => 'string', 'title' => 'city',   'description' => 'City name'],
    'postcode' => ['type' => ['string', 'null'], 'title' => 'postcode'],
  ],
  'required'             => ['street', 'city'],
  'additionalProperties' => false,
]
*/

Extended examples

Nested object schema

$orderSchema = Schema::object('order', 'A customer order', [
    Schema::string('id', 'Order ID')->required(),
    Schema::object('customer', 'Customer details', [
        Schema::string('name', 'Full name')->required(),
        Schema::string('email', 'Email address')->required(),
    ])->required(),
    Schema::array(
        Schema::object('line_item', properties: [
            Schema::string('sku', 'Product SKU')->required(),
            Schema::integer('quantity', 'Ordered quantity')->required(),
            Schema::number('unit_price', 'Price per unit')->required(),
        ]),
        'items',
        'Line items in the order',
    )->required(),
]);

Enum schema

$prioritySchema = Schema::enum(
    ['low', 'medium', 'high', 'critical'],
    'priority',
    'Issue priority level',
);

// Generates: {"type":"string","title":"priority","description":"Issue priority level","enum":["low","medium","high","critical"]}
echo json_encode($prioritySchema->jsonSchema());

Array of objects

$tagsSchema = Schema::array(
    Schema::object('tag', properties: [
        Schema::string('key')->required(),
        Schema::string('value')->required(),
    ]),
    'tags',
    'Key-value metadata tags',
);

$result = Generate::text()
    ->prompt('Extract tags from the following text: ...')
    ->output($tagsSchema)
    ->run();

foreach ($result->output as $tag) {
    echo "{$tag['key']}: {$tag['value']}\n";
}

Core Classes

Results & Responses

Contracts & Enums

Schema: Fluent JSON Schema Builder for Tools and Output

Constants

Factory methods

`string()`

`integer()`

`number()`

`boolean()`

`array()`

`object()`

`enum()`

Modifiers

`required()`

`nullable()`

Accessors

`name()`

`description()`

`type()`

`isRequired()`

`isNullable()`

`items()`

`properties()`

`enumValues()`

`jsonSchema()`

Extended examples

Nested object schema

Enum schema

Array of objects

Build docs developers (and LLMs) love

Core Classes

Results & Responses

Contracts & Enums

Documentation Index

​Constants

​Factory methods

​string()

​integer()

​number()

​boolean()

​array()

​object()

​enum()

​Modifiers

​required()

​nullable()

​Accessors

​name()

​description()

​type()

​isRequired()

​isNullable()

​items()

​properties()

​enumValues()

​jsonSchema()

​Extended examples

​Nested object schema

​Enum schema

​Array of objects

Build docs developers (and LLMs) love

Constants

Factory methods

`string()`

`integer()`

`number()`

`boolean()`

`array()`

`object()`

`enum()`

Modifiers

`required()`

`nullable()`

Accessors

`name()`

`description()`

`type()`

`isRequired()`

`isNullable()`

`items()`

`properties()`

`enumValues()`

`jsonSchema()`

Extended examples

Nested object schema

Enum schema

Array of objects