Skip to main content
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

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

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

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

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 instead.