---
title: "Create Schema"
method: POST
path: "/extract/schemas"
tags: ["/extract"]
---

# Create Schema

`POST /extract/schemas`

## Request

- Base URL: `https://api.contextual.ai/v1`
- URL: `https://api.contextual.ai/v1/extract/schemas`
- Auth: HTTP bearer

Create a new extraction schema.

Creates a JSON Schema that defines the structure of data to extract from documents. The schema must conform to our supported subset of JSON Schema 2020-12 features.

Supported Schema Features:

Basic Types:

1. `string`: Text data with optional constraints (`minLength`, `maxLength`, `pattern`, `enum`)
2. `integer`: Whole numbers with optional constraints (`minimum`, `maximum`, `enum`)
3. `number`: Decimal numbers with optional constraints (`minimum`, `maximum`, `enum`)
4. `boolean`: True/false values
5. `null`: Null values (often used with `anyOf` for optional fields)

Complex Types:

1. `object`: Key-value pairs with defined properties
2. `array`: Lists of items with defined item schemas
3. `anyOf`: Union types (e.g., string or null for optional fields)

String Formats:

Supported formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`, `uri`

Schema Structure:

1. Root schema must be an `object` type
2. Use `$defs` for reusable schema components
3. Use `$ref` to reference definitions
4. Arrays must have `items` schema defined

Constraints:

1. Maximum 10 leaf nodes per array (prevents overly complex schemas)
2. No circular references in `$ref` definitions
3. String formats must be from the supported list

Example Schemas:

Simple Company Schema:
```json
{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "description": "The name of the company exactly as it appears in the document"
    },
    "form_type": {
      "type": "string",
      "enum": ["10-K", "10-Q", "8-K", "S-1"],
      "description": "The type of SEC form"
    },
    "trading_symbol": {
      "type": "string",
      "description": "The trading symbol of the company"
    },
    "zip_code": {
      "type": "integer",
      "description": "The zip code of the company headquarters"
    }
  },
  "required": ["company_name", "form_type", "trading_symbol", "zip_code"]
}
```

Complex Resume Schema:
```json
{
  "type": "object",
  "properties": {
    "personalInfo": {
      "type": "object",
      "properties": {
        "fullName": {"type": "string"},
        "contact": {
          "type": "object",
          "properties": {
            "emails": {
              "type": "array",
              "items": {"type": "string", "format": "email"}
            },
            "phones": {
              "type": "array",
              "items": {"type": "string"}
            }
          }
        }
      },
      "required": ["fullName"]
    },
    "workExperience": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "jobTitle": {"type": "string"},
          "company": {"type": "string"},
          "startDate": {"type": "string"},
          "endDate": {"type": ["string", "null"]},
          "isCurrent": {"type": "boolean"}
        },
        "required": ["jobTitle", "company", "startDate"]
      }
    }
  },
  "required": ["personalInfo", "workExperience"]
}
```

Schema with References:
```json
{
  "type": "object",
  "properties": {
    "algorithms": {
      "type": "array",
      "items": {"$ref": "#/$defs/algorithm"}
    }
  },
  "$defs": {
    "algorithm": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "description": {"type": "string"}
      },
      "required": ["name"]
    }
  }
}
```

Best Practices:

1. Use descriptive field names that clearly indicate what data should be extracted
2. Add detailed descriptions to help the AI understand what to extract
3. Use `enum` for known values (e.g., form types, status values)
4. Make fields optional by using `anyOf` with `null` or omitting from `required`
5. Use arrays for lists of similar items (e.g., work experience, education)
6. Keep schemas focused - avoid overly complex nested structures
7. Test with sample documents to ensure the schema captures the expected data

## Request body

- SchemaCreateRequest: Request model for creating a new extraction schema. The schema_definition must be a valid JSON Schema that defines the structure of data to extract from documents. The system supports a subset of JSON Schema 2020-12 features optimized for document extraction.
  - `name` string, required: Name of the schema
  - `description` string, nullable: Description of the schema
  - `schema_definition` object, required: JSON Schema definition. Must be a valid JSON Schema that defines the structure of data to extract from documents. See the comprehensive schema guide in the API documentation for detailed examples and supported features.
  - `metadata` object, nullable: Additional metadata for the schema

## Response `200`

Successful Response

- SchemaResponse: Response model for schema information.
  - `schema_id` string, required: Unique ID of the schema
  - `name` string, required: Name of the schema
  - `description` string, nullable: Description of the schema
  - `schema_definition` object, required: JSON schema definition
  - `metadata` object, required: Schema metadata
  - `created_at` string, required: Timestamp when the schema was created
  - `updated_at` string, required: Timestamp when the schema was last updated

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `4abdda722de9`: 1 info
  - endpoint added
- **2026-01-13** `ca7f807eec8b`: 1 breaking
  - api path removed without deprecation
- **2025-10-28** `c8152db45500`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/contextualai/apis/endpoints/changes/extract/schemas/post.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) - [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/contextualai/apis/endpoints/revisions/4abdda722de9?raw)