Structured Output Validation Loops

LLMs are good at turning messy input into useful summaries, classifications, and extracted fields. The problem starts when an application treats that text as if it were already dependable data.

A support ticket classifier cannot store "probably urgent" when the database expects low, medium, high, or critical. A claim intake system cannot silently accept a date that is impossible. A CRM enrichment job cannot create a customer record with a missing email and hope someone notices later.

Structured output is the boundary between "the model said something plausible" and "the application accepted a valid value."

Working rule: the model can propose data. The application decides whether that data is usable.

The production problem

Most LLM demos stop after a response appears on screen. Production code has to answer harder questions:

Without a clear boundary, the same defensive code gets copied across controllers, jobs, services, and queue handlers. Each copy has slightly different parsing, error handling, and logging behavior.

That is how an AI feature becomes hard to operate: not because the model is useless, but because the application never made the model cross a real contract.

A concrete example

Assume a customer sends this message:

Subject: Payment failed again

Our checkout has rejected three customer payments since 09:10 UTC.
The Billing API is returning 502s. Please route this to finance ops.
This is blocking live orders.

The application wants an incident object:

use DateTimeInterface;
use Symfony\Component\Validator\Constraints as Assert;

final readonly class Incident
{
    public function __construct(
        #[Assert\NotBlank]
        public string $service,

        #[Assert\Choice(choices: ['low', 'medium', 'high', 'critical'])]
        public string $severity,

        #[Assert\NotBlank]
        public string $owner,

        #[Assert\Choice(choices: ['open', 'triaged', 'closed'])]
        public string $status,

        #[Assert\DateTime(format: DateTimeInterface::ATOM)]
        public string $reportedAt,
    ) {}
}

The important part is not the syntax. The important part is that the application now has a contract: the response must become an Incident, or it is not accepted.

What failure looks like

A plausible model response can still be unusable:

{
  "service": "Billing API",
  "severity": "urgent",
  "owner": "finance ops",
  "status": "needs attention",
  "reportedAt": "this morning"
}

This is a decent human summary. It is not valid application data.

This is the point where hand-rolled code often gets messy:

// This tends to spread through the codebase over time.
$payload = json_decode($modelResponse, true);

$severity = match (strtolower($payload['severity'] ?? '')) {
    'critical', 'urgent', 'blocked' => 'critical',
    'high' => 'high',
    default => 'medium',
};

// Someone still has to normalize status, parse vague dates,
// decide whether the record is safe to store, and log what happened.

That code may be necessary in some systems, but it should not be hidden inside every feature that calls an LLM. It is boundary logic. It belongs at the boundary.

How InstructorPHP handles the boundary

InstructorPHP lets the application ask for a PHP response model and then validates the generated object before returning it to the rest of the app.

The runnable version of this flow lives in the InstructorPHP examples: Structured output validation loop.

use Cognesy\Instructor\Enums\OutputMode;
use Cognesy\Instructor\StructuredOutput;
use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Polyglot\Inference\LLMProvider;

$runtime = StructuredOutputRuntime::fromProvider(
    LLMProvider::using('openai')->withModel('gpt-4o-mini'),
)
    ->withOutputMode(OutputMode::Json)
    ->withMaxRetries(2);

$extracted = (new StructuredOutput($runtime))
    ->with(
        messages: $customerMessage,
        responseModel: Incident::class,
    )
    ->get();

On the first attempt, the model might produce the invalid payload above. The validation layer can turn that into precise feedback:

severity: The value "urgent" is not valid. Expected one of: low, medium, high, critical.
status: The value "needs attention" is not valid. Expected one of: open, triaged, closed.
reportedAt: The value "this morning" is not a valid DateTime string.

The retry prompt is no longer a vague "try again." It can tell the model exactly what failed and what shape is required.

{
  "service": "Billing API",
  "severity": "critical",
  "owner": "finance ops",
  "status": "open",
  "reportedAt": "2026-07-11T09:10:00+00:00"
}

Now the application receives a typed value that can be passed to ordinary business code:

$incident = $incidentRepository->create(
    service: $extracted->service,
    severity: $extracted->severity,
    owner: $extracted->owner,
    status: $extracted->status,
    reportedAt: new DateTimeImmutable($extracted->reportedAt),
);

$router->route($incident);

The controller or job does not need to know how JSON was repaired. It receives an accepted object or an error path it can handle deliberately.

The practical gain: LLM variability is isolated. Application code works with normal PHP types, validators, repositories, and workflow services.

What the loop should record

Validation and repair are only useful if they are observable. At minimum, log enough to answer these questions later:

• What input did the application ask the model to process?
• What raw response failed validation?
• Which fields failed, and why?
• How many repair attempts were needed?
• What object was finally accepted?
• Did the request fail after all retries?

That does not mean storing sensitive raw prompts forever. It means treating the LLM call like any other production integration: with redaction, correlation IDs, retry metadata, and enough evidence for debugging.

For the concrete InstructorPHP mechanisms behind those records, see InstructorPHP observability, logging, and telemetry.

logger()->info('incident_extraction.accepted', [
    'service' => $incident->service,
    'severity' => $incident->severity,
    'owner' => $incident->owner,
    'status' => $incident->status,
    'retry_count' => $retryCount,
    'source' => 'support_ticket',
]);

What this means for business systems

Structured output validation is not mainly a developer convenience. It changes the risk profile of AI-assisted workflows.

The business value is not that the model becomes perfect. It does not. The value is that imperfect model output is forced through a visible, testable, recoverable boundary.

That boundary makes app code cleaner:

// The service receives a domain-shaped value.
// It does not parse model prose, inspect JSON, or guess missing fields.
$triageService->openIncident($incident);

It also makes failures easier to reason about. A failed extraction is not a mysterious bad string buried in a database row. It is a validation failure with a field name, error message, attempt count, and decision.

A sensible operating model

Use structured output validation when an LLM result crosses an application boundary: persistence, workflow routing, customer-visible action, billing, compliance, alerts, or analytics.

Do not use it to pretend every model response is deterministic. Use it to make the uncertainty explicit.

A practical implementation usually has four parts:

1. Define the response model in PHP.
2. Add validation constraints for fields the business actually depends on.
3. Allow a small number of repair attempts with specific validation feedback.
4. Log accepted objects and failed attempts with enough context for operations.

That is the core idea behind InstructorPHP structured output: keep the model useful, but make the application boundary strict.