Structured output

Basic strategy

1. Check whether the model supports structured output.
2. Use the smallest, clearest structure possible.
3. Parse JSON and validate the schema on the server side.
4. On validation failure, retry a limited number of times, or fall back to plain text parsing.

JSON object example

{
  "model": "YOUR_APIONE_MODEL_ID",
  "messages": [
    {"role": "system", "content": "Return JSON only, without Markdown."},
    {"role": "user", "content": "Extract product name and quantity: order 3 blue keyboards."}
  ],
  "response_format": {"type": "json_object"}
}

Server-side validation

function parseOrder(text) {
  const value = JSON.parse(text);
  if (typeof value.product !== "string") throw new Error("product is required");
  if (!Number.isInteger(value.quantity) || value.quantity < 1) {
    throw new Error("quantity must be a positive integer");
  }
  return value;
}

Truncation and finish reason

Schema design suggestions

• Keep field names short and unambiguous.
• Limit enums to the necessary range.
• Avoid deep nesting and unbounded arrays.
• Use strings for amounts, times, and identifiers, and validate their format separately.
• State explicitly which fields allow null.
• Do not let the model decide permissions, final prices, or security policy.