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

# When the answer must follow a schema

> JSON-looking text, valid JSON and a schema-valid result are different promises.

An application may need data it can process safely, not a paragraph it must interpret. For example, an expense classifier might require an object containing a category and an explanation.

That request is more specific than “return something that looks like JSON.” Gateway must preserve the declared output contract from planning through validation and delivery.

## Define the promise precisely

These illustrative results show the difference:

```json theme={null}
{"category": "travel", "explanation": "A train ticket for a work trip."}
```

The value is valid JSON. Whether it satisfies the application's schema also depends on the allowed category values, required fields and types. A parseable object with `"category": 42` could still violate that contract.

The example is teaching data, not a Gateway API request or a claim about a real invoice.

## Check the complete capability combination

An offering that supports reasoning and one that supports constrained output cannot be treated as supporting both together without evidence for that combination.

The planner must establish the required schema behavior, reasoning controls, capacity and delivery mode before execution. An adapter may not turn reasoning off or downgrade to plain text simply because the native request is harder to encode.

Unknown mandatory capability means the candidate is not eligible. It does not justify a paid experiment disguised as a normal request.

## Hold the result until the contract is checked

For the validated-document mode, the provider may stream internally while Gateway assembles the response within bounded resources. The application does not receive a supposedly valid document until validation has actually passed and the required final persistence is confirmed.

```mermaid theme={null}
%%{init: {"flowchart": {"nodeSpacing": 20, "rankSpacing": 30, "padding": 12}}}%%
flowchart TB
    A["Declare the schema"] --> B["Plan a compatible call"]
    B --> C["Generate and assemble"]
    C --> D{"Valid result?"}
    D -->|Yes| E["Confirm<br/>evidence"]
    E --> F["Release result"]
    D -->|No| G["Contract<br/>failure"]
```

The failure branch still has an execution history. Provider work may already have incurred cost even though the application receives no accepted document.

## Do not silently repair the answer

Malformed or schema-invalid output is not automatically a provider-availability failure. It should not be treated as permission to rotate accounts, select another model or ask for another generation without the applicable policy.

Any specifically authorized recovery must still respect the original call, remaining limits and exposure boundary. Default behavior is not to repair or downgrade the result and relabel it successful.

## Valid structure is not valid business work

A schema-valid category can still be wrong. The application remains responsible for its acceptance criteria and any subsequent action.

A tool-call object is also only data. It does not give Gateway permission to execute the tool or make a financial posting. When the application promises later access to the exact validated result, it must retain those bytes outside Gateway's content-free evidence store.

See [Who owns what](/public/gateway/architecture/responsibilities) for those responsibilities and [Execution evidence](/public/gateway/records/execution-evidence) for the record that remains when a document cannot be accepted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.