From 38b4501f020b33336f9080da2c0e3244e27e1200 Mon Sep 17 00:00:00 2001 From: Krivoblotsky Date: Wed, 29 Apr 2026 17:48:02 +0300 Subject: [PATCH] docs(readme): clarify response_format vs text for structured outputs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Structured Outputs section implied both ChatQuery and CreateModelResponseQuery share a single response-format parameter, but they don't: ChatQuery uses responseFormat:, while CreateModelResponseQuery uses text:. The naming mirrors the OpenAI API's own response_format / text fields, so this is intentional — the README just didn't say so. Add a note at the top of the section explaining both spellings, and fix the bullet under JSONSchemaDefinition.derivedJsonSchema that only mentioned responseFormat. Closes #392 Co-Authored-By: Claude Opus 4.7 --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 12576326..899d23cf 100644 --- a/README.md +++ b/README.md @@ -743,6 +743,13 @@ Review [Audio Documentation](https://platform.openai.com/docs/api-reference/audi To configure structured outputs you would define a JSON Schema and pass it to a query. +> [!NOTE] +> The two query types pass the schema via different parameters, mirroring the OpenAI API: +> - `ChatQuery` (Chat Completions API): `responseFormat: .jsonSchema(...)` — encoded as `response_format`. +> - `CreateModelResponseQuery` (Responses API): `text: .jsonSchema(...)` — encoded as `text`. +> +> Both accept the same `JSONSchemaDefinition` value, so the schema-building examples below apply to either query type. + This SDK supports multiple ways to define a schema; choose the one you prefer.
@@ -825,7 +832,7 @@ for output in response.output { Use [Pydantic](https://docs.pydantic.dev/latest/) or [Zod](https://zod.dev) fashion to define schemas. -- Use the `derivedJsonSchema(_ type:)` response format when creating a `ChatQuery` or `CreateModelResponseQuery` +- Use the `derivedJsonSchema(_ type:)` schema definition. Pass it via `responseFormat:` for `ChatQuery` or via `text:` for `CreateModelResponseQuery`. - Provide a type that conforms to `JSONSchemaConvertible` and generates an instance as an example - Make sure all enum types within the provided type conform to `JSONSchemaEnumConvertible` and generate an array of names for all cases