Define your output

A JSON Schema is the contract for the generated answer. It names the fields your application will read, restricts their values and describes what the model should infer. You can send it directly with a request or register it for reuse.

Choose a type that matches the answer

Answer you need	Schema construct
A category from a known set	enum
A yes/no decision	type: "boolean"
Extracted or generated text	type: "string", usually with maxLength
A quantity	integer or number; generation constraints have defined limits
Several named values	object with properties
A list of values or objects	array with items and a useful maxItems
A fixed value	const

Use meaningful category names rather than arbitrary letters. Keep fields only when the application needs them. A nested object or an array item has its own schema, so the same rules apply at each level.

Example: two independent decisions

This schema asks for a department and a duplicate-charge flag. The descriptions explain the categories and the evidence needed for the boolean.

triage.schema.json

Download JSON Schema

{
  "type": "object",
  "properties": {
    "department": {
      "type": "string",
      "enum": [
        "billing",
        "technical",
        "other"
      ],
      "description": "Route charges, invoices and refunds to billing. Route broken product behavior to technical. Use other for anything else."
    },
    "duplicate": {
      "type": "boolean",
      "description": "True only when the message explicitly reports being charged more than once for the same purchase."
    }
  },
  "required": [
    "department",
    "duplicate"
  ],
  "additionalProperties": false
}

properties declares the fields. required lists those that must appear. additionalProperties: false prevents undeclared fields. These structural rules work alongside the descriptions; descriptions guide interpretation but do not enforce arbitrary business rules.

Send the schema

Save the file as triage.schema.json and run the client beside it:

Before you run this example

Call https://api.blatent.ai from your server. Set your API key in the same terminal where you run the example:

export BLATENT_API_KEY='YOUR_SERVICE_KEY'

Python requires Python 3.10+ and HTTPX:

python -m pip install "httpx>=0.28,<1"

TypeScript requires Node.js 24+ and uses its built-in fetch. The cURL examples require curl and jq.

Save the displayed files and the selected client in one directory. Run the client there with python example.py, node example.ts or bash example.sh. Downloads use the example's name in place of example.

Download Python

Python

import json
import os
from pathlib import Path
import httpx

request = {
    "input": "The invoice was charged twice. Can you help me get the duplicate charge refunded?",
    "schema": json.loads(Path("triage.schema.json").read_text(encoding="utf-8")),
}
with httpx.Client(
    base_url="https://api.blatent.ai",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    timeout=195,
) as client:
    response = client.post("/v1/resolve", json=request)
    response.raise_for_status()
    print(json.dumps(response.json()["output"]))

TypeScript

import { readFileSync } from "node:fs";

const request = {
    "input": "The invoice was charged twice. Can you help me get the duplicate charge refunded?",
    "schema": JSON.parse(readFileSync("triage.schema.json", "utf8")),
};
const response = await fetch(
  "https://api.blatent.ai" + "/v1/resolve",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BLATENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(request),
    signal: AbortSignal.timeout(195_000),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(JSON.stringify((await response.json()).output));

cURL

set -eu

body=$(jq -n --argjson body '{"input":"The invoice was charged twice. Can you help me get the duplicate charge refunded?"}' \
  --slurpfile f0 'triage.schema.json' \
  '$body | setpath(["schema"]; $f0[0])')
curl --fail-with-body --silent --show-error \
  "https://api.blatent.ai/v1/resolve" \
  -H "Authorization: Bearer $BLATENT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary "$body"

Illustrative output: {"department":"billing","duplicate":true}. The client reads the generated value from the response's output field.

Decide how to represent missing information

Omitting a field and returning null are different. A property outside required may be absent. A present property may be null only if its schema permits null—for example, type: ["string", "null"].

For classification, an explicit unknown or other enum value can represent insufficient evidence. Describe when to choose it. Making a field required without allowing an honest missing-information outcome can pressure the model to guess.

Add rules where needed

Use string constraints for length limits and custom patterns, and standard formats for dates and timestamps. Use conditions when one output changes which fields or values are legal, or OPA for relationships such as a total matching its items or an outcome requiring supplied permissions.

Struct supports a defined generation subset of JSON Schema 2020-12. Unsupported constraints cause an error; they are not silently ignored. Check the support reference when introducing a new keyword.