Return Structured AI Objects

Structured AI responses allow AI providers to return predictable object-based output instead of free-form text.

This makes AI responses easier to:

• Validate,
• Process programmatically,
• Store in databases,
• Use in workflows, and
• Integrate with application logic.

Instead of generating unstructured text, the AI provider returns data that follows a defined schema.

Structured AI response workflows

A structured AI workflow typically follows this pattern:

1. Provide a prompt explaining the task.
2. Define the expected output structure.
3. Send optional contextual or reference data.
4. Execute the AI query.
5. Process the structured result.

💡

Insight

Structured AI responses are typically more reliable than free-form AI text generation for automation and workflow scenarios.

Example workflow

1. Define the output schema

Define the structure the AI provider should return:

const schema = {
  type: "object",
  properties: {
    materialsAsMentionedInDrawing: {
      type: "string",
    },
    materials: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          nameAsMentionedInDrawing: { type: "string" },
          whereMentioned: { type: "string" },
          confidence: { type: "number" },
        },
      },
    },
  },
};

The schema defines:

• The overall object structure,
• Required property types,
• Nested object definitions, and
• Array item structures.

Structured schemas improve extraction consistency and allow AI output to be processed directly by workflows, services, and application logic.

2. Call the AI provider

Send the prompt, schema, and optional contextual data to the AI provider:

const result = await ai.queryStructured(
  `What materials are used in the attached drawing?

Known materials:
${JSON.stringify(materials)}`,
  schema,
  { images }
);

This call:

• Sends the AI prompt,
• Provides contextual reference data,
• Defines the structure of the expected response, and
• Returns structured output that can be processed programmatically.

3. Process the structured result

The returned result follows the structure defined in the schema:

{
  "materialsAsMentionedInDrawing": "PMMA or PETG",
  "materials": [
    {
      "name": "PMMA",
      "nameAsMentionedInDrawing": "PMMA",
      "whereMentioned": "Material section",
      "confidence": 95
    },
    {
      "name": "PETG",
      "nameAsMentionedInDrawing": "PETG",
      "whereMentioned": "Material section",
      "confidence": 92
    }
  ]
}

Because the response structure is predictable, the returned data can be:

• Written into entities,
• Used in process workflows,
• Validated,
• Passed to services,
• Displayed in screens, or
• Combined with additional business logic.

Confidence ratings

Structured AI responses often include confidence values.

A confidence value is the AI model’s estimated confidence that a returned value is correct.

For example:

{
  "name": "PMMA",
  "confidence": 95
}

This indicates that the AI model estimates a high likelihood that the extracted material was identified correctly.

💬

Why

Confidence ratings are heuristic estimates generated by the AI model and should not be treated as guaranteed correctness.

Structured responses vs text responses

Structured AI responses are typically better suited for:

• Automation,
• Workflow execution,
• Data extraction,
• Validation,
• Integrations, and
• Backend processing.

Free-form text responses are usually better suited for:

• Drafting emails,
• Generating reports,
• Producing summaries,
• Conversational experiences, and
• Human-readable content.

Related concepts

• AI tool calling
• PDF-based AI extraction
• AI workflows
• Workflow automation
• Service integrations