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

# Json

JSON object mode instructs the model to return its response as a valid JSON object. This is useful when you need structured data that can be easily processed by your application, without defining a full schema.

## Basic Usage

Use `ResponseFormat::jsonObject()` to request JSON output. The `asJsonData()` convenience method decodes the response into a PHP array:

```php theme={null}
<?php

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Data\ResponseFormat;
use Cognesy\Polyglot\Inference\Inference;

$data = Inference::using('openai')
    ->withMessages(Messages::fromString('Return JSON with keys "name" and "role".'))
    ->withResponseFormat(ResponseFormat::jsonObject())
    ->asJsonData();

// $data is now a PHP array, e.g. ['name' => 'Alice', 'role' => 'Engineer']
// @doctest id="3c6c"
```

The `asJsonData()` method only decodes the returned content. Validation and structure depend on the provider and your prompt -- there are no schema guarantees with this mode.

## Guiding the JSON Structure

For best results, include clear instructions about the expected JSON structure directly in your prompt. The model will follow your guidance, but without a schema there is no enforcement:

```php theme={null}
<?php

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Data\ResponseFormat;
use Cognesy\Polyglot\Inference\Inference;

$prompt = <<<EOT
List the top 3 most populous cities in the world.
Return your answer as a JSON object with the following structure:
{
  "cities": [
    {
      "name": "City name",
      "country": "Country name",
      "population": population in millions (number)
    }
  ]
}
EOT;

$data = Inference::using('openai')
    ->with(
        messages: Messages::fromString($prompt),
        responseFormat: ResponseFormat::jsonObject(),
    )
    ->asJsonData();

foreach ($data['cities'] as $city) {
    echo "{$city['name']}, {$city['country']}: {$city['population']} million\n";
}
// @doctest id="a348"
```

## Using the Fluent API

You can also set the response format with the dedicated `withResponseFormat()` method:

```php theme={null}
<?php

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Data\ResponseFormat;
use Cognesy\Polyglot\Inference\Inference;

$data = Inference::using('openai')
    ->withMessages(Messages::fromString('List three programming languages as JSON with name and year fields.'))
    ->withResponseFormat(ResponseFormat::jsonObject())
    ->asJsonData();
// @doctest id="269d"
```

## Getting JSON as a String

If you need the raw JSON string instead of a decoded array, use `asJson()`:

```php theme={null}
<?php

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Data\ResponseFormat;
use Cognesy\Polyglot\Inference\Inference;

$json = Inference::using('openai')
    ->withMessages(Messages::fromString('Return a JSON object with a greeting.'))
    ->withResponseFormat(ResponseFormat::jsonObject())
    ->asJson();

// $json is a string like '{"greeting": "Hello, world!"}'
// @doctest id="3d4a"
```

## Provider Support

Most major providers support native JSON object mode, including OpenAI, Groq, Fireworks, and others. Some providers (such as Anthropic) do not support `responseFormat` natively -- for those, consider using tool calls to extract structured data, or use the Instructor layer above Polyglot for prompt-based fallback strategies.

You can query a driver's capabilities programmatically through `DriverCapabilities::supportsResponseFormatJsonObject()`.

## When to Use JSON Object Mode

JSON object mode is ideal for:

* Extracting structured data (lists, records, key-value pairs)
* API responses that need to be machine-readable
* Generating datasets or feeding data into downstream processing
* Cases where you want structured output but do not need strict schema validation

If you need guaranteed field names, types, and required properties, consider [JSON Schema mode](/modes/json-schema) instead.