Structured and JSON output

Getting parseable output from Aimogen Pro prompts - JSON, lists and delimited formats - and how the PHP API helps.

Sometimes you need output a program can read, not prose. Aimogen Pro gives you three routes.

1. The PHP API extract method#

The cleanest option when you are writing code. extract() appends schema instructions, strips markdown fences and decodes the JSON:

$response = aimogen()->extract(
    'Extract the product details from this text: ' . $description,
    array(
        'name'     => 'string',
        'price'    => 'number',
        'features' => array( 'string' ),
        'in_stock' => 'boolean',
    )
);

if ( $response->ok() ) {
    $data = $response->data();
    echo esc_html( $data['name'] );
} else {
    error_log( 'Extraction failed: ' . $response->error() );
}

It handles the two things that break naive JSON extraction: models wrapping output in ```json fences, and invalid JSON. A decode failure returns a failed response with the raw text in the meta, rather than a fatal error.

See PHP API.

2. Prompting for JSON#

Where you cannot use the PHP API — in a rule prompt or an OmniBlock — ask for JSON explicitly and be strict about it:

Extract the following from the text below. Return ONLY valid JSON, with no
markdown fences, no explanation and no text before or after.

Schema:
{"name": string, "price": number, "features": [string], "in_stock": boolean}

If a value is not present in the text, use null. Do not invent values.

Text:
%%post_content_plain_text%%

What matters in that prompt:

• "ONLY valid JSON", stated first
• "no markdown fences" — the single most common failure
• An explicit schema
• A rule for missing values — otherwise the model invents them
• The input last, so the instructions are not buried

3. Delimited formats#

Often more robust than JSON, because there is less to get syntactically wrong:

Return one item per line, in the format:
NAME | PRICE | AVAILABILITY

No header row, no numbering, no other text.

A pipe-delimited line is easier for a model to produce correctly than nested JSON, and easier to parse tolerantly. For flat data, prefer it.

Model choice#

Instruction adherence varies. Current OpenAI GPT-5 and Anthropic Claude models follow format instructions reliably. Small open models frequently add commentary regardless of what you ask.

If structured output is unreliable, change the model before rewriting the prompt for the fifth time. See Selecting models.

Temperature#

Lower it. For extraction and structured output, 0.2 to 0.5 produces far more consistent formatting than the default 1.

Cleaning up afterwards#

Run Regex On Content on a rule post-processes output. Stripping markdown fences:

Regex:       ^```(?:json)?\s*|\s*```$
Replacement: (leave empty)

That handles the most common failure without touching the prompt.

Validating#

Never trust structured output without checking it:

$response = aimogen()->extract( $prompt, $schema );

if ( $response->failed() ) {
    return;
}

$data = $response->data();

if ( ! isset( $data['name'], $data['price'] ) ) {
    error_log( 'Aimogen: unexpected shape from extraction' );
    return;
}

$price = is_numeric( $data['price'] ) ? (float) $data['price'] : 0.0;

A model can return valid JSON with the wrong keys, or a string where you expected a number.

Using structured output in workflows#

The pattern in OmniBlocks:

1. An ai_text block produces JSON.
2. A process_and_transform_data step or a diy block parses it.
3. Later blocks use the parsed values.

Or simpler: ask for one value per AI block. Three cheap blocks returning one field each are more reliable than one block returning three fields as JSON, and easier to debug.

Common problems#

Markdown fences around the JSON. Say "no markdown fences", or strip them with regex.

Explanatory text before the JSON. Say "no text before or after". Lower the temperature.

Invalid JSON. Usually an unescaped quote inside a string. Ask for a delimited format instead.

Fields invented when data is missing. State the rule for missing values explicitly.

Inconsistent between runs. Temperature too high.

Related#

• PHP API
• Prompt best practices
• Debugging prompts