Structured Output / JSON responses

Use structured output when you need a consistent AI answer that your code can parse.

Structured output forces every AI answer into a JSON schema, in place of free text. Use it in an application that processes the AI answer in code, that reads a specific field, or that writes the AI result into a table or a workflow.

How it works

You give a JSON schema to UC AI, and the AI model then answers only in that format. The schema defines the structure, the data types, the required fields, and the validation rules of the answer.

UC AI converts your JSON schema to the format of each AI provider. These providers support structured output:

JSON Schema

JSON schema is a standard for the structure and the validation rules of JSON data. With it, you define the format, the data types, and the required fields of an API answer. A JSON schema is itself JSON. The official page has more information.

This schema forces an answer with a text and a confidence score between 0 and 1.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Simple AI Response",
  "description": "A basic response format for AI tools that return text with a confidence score",
  "properties": {
    "response": {
      "type": "string",
      "description": "The generated response text"
    },
    "confidence": {
      "type": "number",
      "description": "Confidence score between 0 and 1",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": ["response", "confidence"]
}

An answer then looks like this:

{
  "response": "The capital of France is Paris.",
  "confidence": 1
}

Use our JSON schema builder to write a valid schema. The builder has more examples, and you can edit an existing schema in it.

Example: Simple confidence scoring

This example returns an answer with a confidence score. Use such a score for quality control and for a decision.

DECLARE
  l_result json_object_t;
  l_schema json_object_t := json_object_t();
  l_structured_output json_object_t;
BEGIN
  l_schema := q'#
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Simple AI Response",
  "description": "A basic response format for AI tools that return text with a confidence score",
  "properties": {
    "response": {
      "type": "string",
      "description": "The generated response text"
    },
    "confidence": {
      "type": "number",
      "description": "Confidence score between 0 and 1",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": ["response", "confidence"]
}#';

  -- Generate structured response
  l_result := uc_ai.generate_text(
    p_user_prompt => 'What is the capital of France? Please respond with a confidence score.',
    p_system_prompt => 'You are a helpful assistant that provides accurate information.',
    p_provider => uc_ai.c_provider_openai,
    p_model => uc_ai_openai.c_model_gpt_5_6_luna,
    p_response_json_schema => l_schema
  );

  -- Extract structured data from the final message
  l_structured_output := json_object_t(l_result.get_clob('final_message'));

  dbms_output.put_line('Response: ' || l_structured_output.get_string('response'));
  dbms_output.put_line('Confidence: ' || l_structured_output.get_number('confidence'));
  -- Response: The capital of France is Paris.
  -- Confidence: 1
END;
/

Schema best practices

Write a clear description for each field
Set the constraints: an enum, a minimum value, and a maximum value
Mark every required field