JSON Schema Reference - Narrative I/O Knowledge Base

Model Inference uses JSON Schema to define the structure of responses. This reference documents supported features and patterns.

Supported draft version

Model Inference validates output_format_schema against JSON Schema Draft 2019-09 on the server side after each inference call. Draft 2020-12 features commonly used for structured output definition are also supported.

Schema requirements

A few constraints apply to every output_format_schema:

The top-level schema must have type: "object".
For forced-tool-use models — currently Claude Sonnet 5.0 and Claude Opus 4.7 / 4.8 — the top-level object must set additionalProperties: false. The forced-tool path rejects a schema that omits it or sets it to true.
The server validates the model’s response against your schema; a violation fails the inference job with a typed error rather than returning invalid data.

Basic types

String

{
  "type": "string"
}

With constraints:

{
  "type": "string",
  "minLength": 1,
  "maxLength": 1000
}

Number

{
  "type": "number"
}

With constraints:

{
  "type": "number",
  "minimum": 0,
  "maximum": 1
}

Integer

{
  "type": "integer",
  "minimum": 0
}

Boolean

{
  "type": "boolean"
}

Null

{
  "type": "null"
}

Object type

Define structured objects with named properties:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "active": { "type": "boolean" }
  },
  "required": ["name", "age"]
}

Required properties

Use the required array to specify mandatory fields:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "title": { "type": "string" },
    "description": { "type": "string" }
  },
  "required": ["id", "title"]
}

Additional properties

Control whether extra properties are allowed:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "additionalProperties": false
}

Array type

Simple arrays

{
  "type": "array",
  "items": { "type": "string" }
}

Array constraints

{
  "type": "array",
  "items": { "type": "string" },
  "minItems": 1,
  "maxItems": 10
}

Arrays of objects

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "value": { "type": "number" }
    },
    "required": ["name", "value"]
  }
}

Enum constraint

Restrict values to a predefined set:

{
  "type": "string",
  "enum": ["low", "medium", "high"]
}

Enum with numbers:

{
  "type": "integer",
  "enum": [1, 2, 3, 4, 5]
}

Numeric constraints

Keyword	Description
`minimum`	Value must be >= this number
`maximum`	Value must be <= this number
`exclusiveMinimum`	Value must be > this number
`exclusiveMaximum`	Value must be < this number
`multipleOf`	Value must be divisible by this number

Example:

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.01
}

String constraints

Keyword	Description
`minLength`	Minimum string length
`maxLength`	Maximum string length
`pattern`	Regex pattern the string must match

Example:

{
  "type": "string",
  "minLength": 1,
  "maxLength": 500,
  "pattern": "^[A-Z][a-z]+$"
}

Array constraints

Keyword	Description
`minItems`	Minimum array length
`maxItems`	Maximum array length
`uniqueItems`	All items must be unique

Example:

{
  "type": "array",
  "items": { "type": "string" },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}

Descriptions

Add descriptions to help the model understand field purpose:

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positive", "negative", "neutral"],
      "description": "The overall emotional tone of the text"
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Confidence score where 0 is uncertain and 1 is certain"
    }
  },
  "required": ["sentiment", "confidence"]
}

Nested structures

Nested objects

{
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {
        "created_at": { "type": "string" },
        "version": { "type": "integer" }
      },
      "required": ["created_at"]
    },
    "data": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    }
  },
  "required": ["metadata"]
}

Common patterns

Classification result

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["A", "B", "C", "D"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "reasoning": {
      "type": "string"
    }
  },
  "required": ["category", "confidence"]
}

Entity extraction

{
  "type": "object",
  "properties": {
    "entities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": { "type": "string" },
          "type": {
            "type": "string",
            "enum": ["person", "organization", "location", "date"]
          },
          "start_index": { "type": "integer" },
          "end_index": { "type": "integer" }
        },
        "required": ["text", "type"]
      }
    }
  },
  "required": ["entities"]
}

Summary with key points

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "maxLength": 500
    },
    "key_points": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 5
    },
    "word_count": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["summary", "key_points"]
}

CRON expression result

{
  "type": "object",
  "properties": {
    "cron_expression": {
      "type": "string",
      "pattern": "^[\\d\\*\\/\\-\\,]+\\s+[\\d\\*\\/\\-\\,]+\\s+[\\d\\*\\/\\-\\,\\?LW]+\\s+[\\d\\*\\/\\-\\,]+\\s+[\\d\\*\\/\\-\\,\\?L#]+$",
      "description": "Valid CRON expression"
    },
    "human_readable": {
      "type": "string",
      "description": "Human-readable description of the schedule"
    },
    "next_runs": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 3,
      "description": "Next 3 scheduled execution times in ISO format"
    }
  },
  "required": ["cron_expression", "human_readable"]
}

TypeScript mapping

JSON Schema Type	TypeScript Type
`string`	`string`
`number`	`number`
`integer`	`number`
`boolean`	`boolean`
`null`	`null`
`array`	`T[]`
`object`	`{ [key: string]: T }`
`enum`	Union type (`'a' \| 'b' \| 'c'`)

Using Structured Output

Practical guide to schema definition

Model Inference API

Complete API reference

Structured Output Concepts

Why structured output matters

Running Inference

Submit inference requests

​Supported draft version

​Schema requirements

​Basic types

​String

​Number

​Integer

​Boolean

​Null

​Object type

​Required properties

​Additional properties

​Array type

​Simple arrays

​Array constraints

​Arrays of objects

​Enum constraint

​Numeric constraints

​String constraints

​Array constraints

​Descriptions

​Nested structures

​Nested objects

​Common patterns

​Classification result

​Entity extraction

​Summary with key points

​CRON expression result

​TypeScript mapping

​Related content

Using Structured Output

Model Inference API

Structured Output Concepts

Running Inference

Supported draft version

Schema requirements

Basic types

String

Number

Integer

Boolean

Null

Object type

Required properties

Additional properties

Array type

Simple arrays

Array constraints

Arrays of objects

Enum constraint

Numeric constraints

String constraints

Array constraints

Descriptions

Nested structures

Nested objects

Common patterns

Classification result

Entity extraction

Summary with key points

CRON expression result

TypeScript mapping

Related content