> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema

Schemas define the structured output you expect from Retab. They are standard JSON Schema objects used by extraction, processor, and workflow calls to validate the data returned from documents.

Use `POST /v1/schemas/generate` when you want Retab to infer a schema from example documents.

## Generate Schema

The schema generation endpoint accepts one or more documents and returns a JSON Schema inferred from those examples. You can pass optional instructions and model routing.

<CodeGroup>
  ```python Python theme={null}
  from retab import Retab

  client = Retab()

  schema = client.schemas.generate(
  documents=[
  "freight/booking_confirmation_1.jpg",
  "freight/booking_confirmation_2.jpg",
  ],
  model="retab-small",
  instructions="Capture shipment dates, parties, and reference numbers.",
  )

  print(schema.json_schema)

  ```

  ```typescript TypeScript theme={null}
  import { Retab } from '@retab/node';

  const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

  const schema = await client.schemas.generate([
      "freight/booking_confirmation_1.jpg",
      "freight/booking_confirmation_2.jpg",
    ], "retab-small", "Capture shipment dates, parties, and reference numbers.");

  console.log(schema.jsonSchema);
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"log"

  	retab "github.com/retab-dev/retab/clients/go"
  )

  func main() {
  	ctx := context.Background()

  	client, err := retab.NewClient("")
  	if err != nil {
  		log.Fatal(err)
  	}

  	firstDocument, err := retab.InferMIMEData("freight/booking_confirmation_1.jpg")
  	if err != nil {
  		log.Fatal(err)
  	}
  	secondDocument, err := retab.InferMIMEData("freight/booking_confirmation_2.jpg")
  	if err != nil {
  		log.Fatal(err)
  	}

  	model := "retab-small"
  	schema, err := client.Schemas.Generate(ctx, &retab.SchemasGenerateParams{
  		Documents: []any{firstDocument, secondDocument},
  		Model:     &model,
  	})
  	if err != nil {
  		log.Fatal(err)
  	}

  	fmt.Println(schema.JSONSchema)
  }
  ```

  ```ruby Ruby theme={null}
  require 'retab'

  client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

  schema = client.schemas.generate(
    documents: [
      'freight/booking_confirmation_1.jpg',
      'freight/booking_confirmation_2.jpg',
    ],
    model: 'retab-small',
    instructions: 'Capture shipment dates, parties, and reference numbers.',
  )

  puts schema.json_schema
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Retab\Client;

  $client = new Client();

  $schema = $client->schemas()->generate(
      documents: [
          'freight/booking_confirmation_1.jpg',
          'freight/booking_confirmation_2.jpg',
      ],
      model: 'retab-small',
      instructions: 'Capture shipment dates, parties, and reference numbers.',
  );

  print_r($schema->jsonSchema);
  ```

  ```java Java theme={null}
  import com.retab.RetabClient;

  public final class Example {
    public static void main(String[] args) throws Exception {
      RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

      var result = client.schemas().generate(null, "retab-1.5", "Extract the invoice fields", null);
      System.out.println(result);
    }
  }
  ```

  ```curl cURL theme={null}
  curl https://api.retab.com/v1/schemas/generate \
    -H "Authorization: Bearer $RETAB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "documents": [
        {
          "filename": "booking_confirmation_1.jpg",
          "url": "data:image/jpeg;base64,..."
        },
        {
          "filename": "booking_confirmation_2.jpg",
          "url": "data:image/jpeg;base64,..."
        }
      ],
      "model": "retab-small",
      "instructions": "Capture shipment dates, parties, and reference numbers."
    }'
  ```

  ```json Response theme={null}
  {
    "object": "schema",
    "created_at": "2026-05-13T12:00:00Z",
    "json_schema": {
      "type": "object",
      "properties": {
        "booking_reference": {
          "type": "string",
          "description": "The booking or shipment reference number."
        },
        "departure_date": {
          "type": "string",
          "description": "The scheduled departure date."
        }
      },
      "required": ["booking_reference", "departure_date"]
    },
    "strict": true
  }
  ```

  ```csharp C# theme={null}
  using System;
  using System.Collections.Generic;
  using System.IO;
  using System.Threading.Tasks;
  using Retab;
  using RetabClient = Retab.Retab;

  var client = new RetabClient("YOUR_API_KEY");

  var schema = await client.Schemas.GenerateAsync(
      new SchemasGenerateOptions
      {
          Documents = new List<MimeData>
          {
              new FileInfo("freight/booking_confirmation_1.jpg"),
              new FileInfo("freight/booking_confirmation_2.jpg"),
          },
          Model = "retab-small",
          Instructions = "Capture shipment dates, parties, and reference numbers.",
      }
  );

  Console.WriteLine(schema.JsonSchema);
  ```

  ```rust Rust theme={null}
  use retab::{resources::schemas::GenerateParams, Retab};

  let client = Retab::new(std::env::var("RETAB_API_KEY")?);
  let schema = client
      .schemas()
      .generate(GenerateParams::new([
          "freight/booking_confirmation_1.jpg",
          "freight/booking_confirmation_2.jpg",
      ]))
      .await?;

  println!("{:#?}", schema.json_schema);
  ```
</CodeGroup>

## Request Fields

<ParamField body="documents" type="MIMEData[]" required>
  Example documents used to infer the schema.
</ParamField>

<ParamField body="model" type="string" default="retab-small">
  Model or Retab router alias used for schema generation.
</ParamField>

<ParamField body="instructions" type="string">
  Extra guidance for fields, naming conventions, or domain-specific details.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Whether to stream schema generation output.
</ParamField>

## Response Fields

<ResponseField name="object" type="string">
  Always `"schema"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp for the generated schema response.
</ResponseField>

<ResponseField name="json_schema" type="object">
  The generated JSON Schema.
</ResponseField>

<ResponseField name="strict" type="boolean">
  Whether the schema should be treated as strict structured output.
</ResponseField>