SPB Git forge
spboucher.ai ↗

spb/doc-api

Public
2commits 1branches 0releases
15.7 MBsize
maindefault branch
13 days agolast push
Python 88.3% TypeScript 7.6% Shell 4.1%
3.2 KB
View source Raw Blame History

# xAI structured outputs — response_format / text.format json_schema, tool-argument conformance

Status: DOCUMENTED + LIVE_VERIFIED (2026-09-19, grok-4.3: chat response_format json_schema strict + json_object, Responses text.format json_schema strict → valid JSON matching the schema). Machine-readable: parameters fragments (response_format.*, text.format.*).

Sources: https://docs.x.ai/developers/model-capabilities/text/structured-outputs · OpenAPI ResponseFormat, ModelResponseFormat Last verified: 2026-09-19

# Request shapes

API Field Shape
Chat Completions response_format {"type":"json_schema","json_schema":{"name":"ok","strict":true,"schema":{…}}} · {"type":"json_object"} · {"type":"text"}
Responses text.format {"type":"json_schema","name":"ok","strict":true,"schema":{…},"description":"…"} · json_object · text
Tools tools[].parameters / input_schema always strictly enforced ("strict flag implicitly true"); strict field accepted and ignored

Live: schema {type:object, properties:{answer:string, n:integer}, required:[answer,n], additionalProperties:false} → chat {"answer":"OK","n":1}, Responses {"answer":"OK","n":1} and response.text.format echoes the schema. json_object → {"ok":true}.

# JSON Schema support (docs)

  • Types: string, number, integer, boolean, null, enum, const, array, object, anyOf, oneOf (= anyOf), allOf (single subschema), $ref/$defs (non-circular). Draft 2020-12 preferred, Draft-07 accepted.
  • additionalProperties defaults to false; set true explicitly to allow extras. Nullable via type arrays or anyOf with null. Non-required fields are optional.
  • Enforced format: date, time, date-time, email, uuid, ipv4, ipv6, uri. Other formats best-effort.
  • Enforced limits: min/max numeric (no limit), minLength/maxLength ≤ 2 048, minItems/maxItems ≤ 256, minProperties/maxProperties ≤ 64; beyond → best-effort.
  • Best-effort (not guaranteed): not, if/then/else, multi-subschema allOf, unknown formats.
  • Rejected (400): empty enum/anyOf, boolean property schemas, maxContains/minContains, items as array (use prefixItems).
  • pattern: ECMA-262 subset — no backreferences, \p{} classes, \b, lookaround, inline modifiers; . matches newlines; anchors implicit (whole-string match); groups non-capturing.

# With tools

Structured output combines with server-side tools and function calling on Grok 4 family models: client.responses.parse(model, input, tools=[{type:"web_search"}], text_format=Model) (OpenAI SDK) or chat.parse(Model) after the tool loop (xai-sdk). Streaming with response_format yields partial JSON in chunk.content.

# SDK helpers

  • OpenAI Python: client.beta.chat.completions.parse(..., response_format=PydanticModel); client.responses.parse(..., text_format=Model) → .output_parsed.
  • OpenAI Node: zodResponseFormat(schema, "name").
  • xai-sdk: chat.parse(Model) → (response, model_instance); or client.chat.create(response_format=Model) + sample()/stream() + Model.model_validate_json(response.content).

Example files: examples/xai/structured-output/.