Skip to main content

Turn a task description into a validated summary object

Section: DOC-MA-model-controls-structured-output#request-a-structured-answer.

Create a summary your application can place in a task card without parsing prose for field names. Send the task description with an object schema, wait for the run outcome and validate the exact answer your application will use.

Start with one summary string and a bounded synchronous wait. Add fields only when the application needs them. Schema validation checks shape and types; it does not establish factual correctness, units, provenance or permission to act.

Before you start​

Section: DOC-MA-model-controls-structured-output#before-you-start.

Use a model and provider route that supports the requested structured format. The native conversation API accepts the configuration below. See model selection and generation.

Create a thread, keep its ID and use the normal user-scoped credentials. Wait for any prior turn to resolve: per-send overrides are not retained for queued messages. The example uses a controlled task description; replace it with content the user is entitled to send.

Step 1: send the task with its object schema​

Section: DOC-MA-model-controls-structured-output#configure-an-object-response.

Use this body with send-message-sync and the thread ID you created. It requests a bounded wait; inspect the returned status before consuming the object:

{
  "conversationKey": "<created-thread-id>",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Summarize this task: Prepare the support onboarding guide and have it reviewed."
      }
    ]
  },
  "overrideGenerationConfig": {
    "responseFormat": {
      "schemaName": "summary",
      "jsonSchema": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "string"
          }
        },
        "required": [
          "summary"
        ],
        "additionalProperties": false
      },
      "validate": true,
      "maxValidationRetries": 1
    }
  }
}

Request example: Send a message and wait for the result · Request fields.

For a recurring task-card flow, move the same responseFormat into its conversation default or profile after testing it. Keep the schema used by the application with the request; the schema name alone does not identify an immutable version.

Step 2: populate the task card only from a completed valid answer​

Section: DOC-MA-model-controls-structured-output#read-and-validate-the-result.

If the bounded response is still active, queued or waiting for a tool, retain its run ID and use generation recovery. Once it completes, parse the answer and validate it against the exact schema above.

A refusal, truncated response, invalid JSON, missing required field or provider error is not a typed success. Handle it explicitly instead of substituting an empty object. A healed value of false or its absence is not reliable evidence about whether provider repair occurred.

Finished result: the card receives one validated summary string whose content you checked against the source task. For refusal, truncation, invalid output or failure, show the failure or unresolved state and leave the card unfilled; do not substitute an empty object and continue.

Variant: show provisional text while waiting for validation​

Section: DOC-MA-model-controls-structured-output#treat-streaming-separately.

Streamed fragments can reach your client before validation finishes, and a validation retry can replace the attempted answer. Keep that text provisional and do not execute actions from it. Wait for a completed result, parse it and validate it before using it; a visible fragment is not a validated answer.

Confirm that the selected model supports the requested output format. Application-level validation remains necessary even when a model supports a strict schema. See model errors for failure handling.

Upcoming recipe: use the same validated-summary flow through a compatible client​

Status: Upcoming — not yet available.

Section: DOC-MA-model-controls-structured-output#compatible-structured-output

Use a supported OpenAI-compatible interface when your application already uses that protocol.

  1. Supply the task and a supported object schema through the compatible request.
  2. Choose validation before display for a task card that cannot consume partial data.
  3. Wait for the distinct validated, refused, incomplete or failed outcome.
  4. Populate the card only from the validated object. A failed provisional stream remains incomplete rather than becoming a replacement successful answer.

Finished result: a validated task summary or an explicit unsuccessful outcome, without an empty summary standing in for success.

Compatible interfaces, supported schemas and client versions are not yet available. The native configuration and current streaming limitations above still apply; changing an SDK base URL does not make native endpoints OpenAI-compatible. See native and compatible streams.

Document ID: DOC-MA-model-controls-structured-output. Section identities and revisions.