Schema rules reference

Overview

The schema defines "which fields to extract from a document and the type of each field", and is a required parameter of an extraction request. The schema of this service is compatible with the LlamaIndex JSON Schema format, but its usage limits are not exactly the same as LlamaIndex (such as nesting depth, field count, and size limits). This document takes precedence.

JSON Schema format

Basic structure

{
  "description": "Invoice information extraction",
  "type": "object",
  "properties": {
    "invoice_number": {"description": "Invoice number", "type": "string"},
    "invoice_date": {"description": "Invoice date, format YYYY-MM-DD", "type": "string"},
    "total_amount": {"description": "Total amount including tax, in CNY", "type": "number"},
    "is_electronic": {"description": "Whether it is an electronic invoice", "type": "boolean"},
    "buyer": {
      "description": "Buyer information",
      "type": "object",
      "properties": {
        "name": {"description": "Buyer name", "type": "string"},
        "tax_id": {"description": "Buyer tax ID", "type": "string"}
      },
      "required": ["name"]
    },
    "line_items": {
      "description": "Line items",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_name": {"description": "Item name", "type": "string"},
          "quantity": {"description": "Quantity", "type": "integer"},
          "amount": {"description": "Amount, in CNY", "type": "number"}
        }
      }
    }
  },
  "required": ["invoice_number", "total_amount"]
}

Format detection

The schema is parsed as JSON Schema format in either of the following cases:

The top level contains all three keys: description, properties, and required;
type is "object", properties is a non-empty object, and every field definition inside it is an object (that is, the standard JSON Schema form, such as output generated by Pydantic).

In all other cases, it is parsed as the legacy description-string format. To avoid ambiguity, always specify "type": "object" at the top level.

Supported types


Type	Description	Example result value
`string`	Text	`"12345"`
`integer`	Integer	`12`
`number`	Number (integer or decimal)	`12.5`
`boolean`	Boolean	`true`
`object`	Nested object; must have `properties`	`{"name": "xx"}`
`array`	Array; must have `items`	`[{"amount": 1}]`

Common patterns

Nullable fields (both forms are acceptable):

"start_date": {
    "anyOf": [
        {
            "type": "string"
        },
        {
            "type": "null"
        }
    ],
    "description": "Start date"
}

"start_date": {
    "type": [
        "string",
        "null"
    ],
    "description": "Start date"
}

Enum values (the result is matched to an enum item as closely as possible):

"payment_type": {
    "description": "Payment method",
    "type": "string",
    "enum": [
        "Wire transfer",
        "Acceptance bill",
        "Check"
    ]
}

Default values (filled in when the field is not extracted and is not required):

"currency": {
    "description": "Currency",
    "type": "string",
    "default": "CNY"
}

Reusing field definitions ($ref only supports the #/$defs/xxx form):

{
  "type": "object",
  "properties": {
    "seller": {"$ref": "#/$defs/Company"},
    "buyer": {"$ref": "#/$defs/Company"}
  },
  "$defs": {
    "Company": {
      "type": "object",
      "properties": {
        "name": {"description": "Company name", "type": "string"},
        "tax_id": {"description": "Tax ID", "type": "string"}
      }
    }
  }
}

Unsupported keywords

Only type, description, title, properties, items, required, enum, default, $defs, $ref, and anyOf are supported. All other JSON Schema keywords (such as format, pattern, minLength, minItems, etc.) are not supported and are ignored. If you need format constraints (such as a date format), write them into the field's description.

Automatic result correction

Extraction results are automatically corrected according to the schema declarations, with no extra processing required:

Type correction: when a value does not match the declared type, the system makes a best-effort conversion, such as "12" → 12 (integer), "12.5" → 12.5 (number), "true" → true (boolean); if conversion fails, the original value is kept; object/array types are not converted.
Enum matching: when a value does not match the enum, the system tries exact match, case-insensitive match, and similarity match in order; if it still does not match, the first enum item is used.
Default value filling: when a field value is null and a default is declared, the default value is filled in.
Array extraction: the array as a whole is returned as a JSON array field, and each field inside the array is likewise corrected according to the types in items.

Limits


Item	Limit	Description
Schema size	≤ 600 KB after serialization in UTF-8	Error 4013 when exceeded
Nesting depth	≤ 6 levels	See the criteria below; error 4012 when exceeded
Leaf field count	≤ 100	Error 4011 when exceeded
Root node	Must be a JSON object	Arrays, strings, etc. return error 4011
`object` field	Must have non-empty `properties`	Error 4011 when missing or empty
`array` field	Must have non-empty `items`	Error 4011 when missing or empty

Depth criteria (JSON Schema format):

Fields under the root-level properties are level 1;
Each entry into the child fields of a nested object adds 1 level;
The items of an array adds 1 level as a whole (when items is an object, its inner fields add 1 more).

Expressed as data paths: a.b.c.d.e.f is 6 levels (valid), a.b.c.d.e.f.g is 7 levels (over the limit); a[ ].b is 3 levels (a is 1 level, items is 1 level, b is 1 level). Leaf field count criteria:

JSON Schema format: objects are recursively expanded and counted; an array counts as 1 field as a whole (its inner fields are not counted);
Legacy format: the number of string leaves.

Recommendation: keep nesting within 3 to 4 levels whenever possible; when there are many fields, split them into multiple extractions and merge the results.

Schema validation tool

Before submitting, you can use the validation script to check offline (script: schema validation tool, consistent with the server-side validation rules):

python3 validate_extract_schema.py schema.json
python3 validate_extract_schema.py --json '{"type":"object","properties":{"a":{"type":"string"}}}'

Output on success:

[PASS] format=llama, leaf fields=3, max depth=3, size=336 bytes

Output on failure includes the error code, reason, and location:

[FAIL] error code 4011: type is object but properties is missing or empty (location: properties.buyer)
[FAIL] error code 4012: extract_schema nesting exceeds the limit of 6 (location: properties.a.b.c.d.e.f.g)

Troubleshooting

When the schema validation tool returns one of the error codes in the following table, the schema failed validation:


Error code	Error name	Meaning	Common causes and fixes
9004	Parameter error	`extract_schema` is not passed or is empty	Add a non-empty `extract_schema` to the request body
4011	EXTRACT_SCHEMA_ERROR	Disallowed schema format	See the common 4011 scenarios below
4012	EXTRACT_SCHEMA_DEPTH_ERROR	Nesting exceeds 6 levels	Reduce nesting levels and flatten the structure
4013	EXTRACT_SCHEMA_SIZE_ERROR	Schema size exceeds 600 KB	Trim description text, reduce fields, or split the extraction

Common 4011 scenarios:


Error message	Cause	Fix
type is object but properties is missing or empty	An object field does not declare child fields	Add non-empty `properties`, or change the field to `string`
type is array but items is missing or empty	An array field does not declare the element structure	Add `items`, for example `"items": {"type": "string"}`
Field count exceeds the limit	Leaf field count exceeds 100 (1,500 in production)	Split into multiple extractions and merge the results
properties is empty	No fields are declared	Declare at least one field
Field description must be a string or an object	A legacy-format leaf value is not a string/object (such as a number or an array)	Change the leaf value to a description string, or switch to the JSON Schema format
Abnormal field paths (for example, `a.description` and `a.type` become extraction fields)	The schema lacks the top-level `type: "object"` and does not meet the three-key detection rule, so it is parsed as the legacy format	Add `"type": "object"` at the top level

Other self-check suggestions:

Validate locally with the validation script; errors report the exact location;
Confirm the JSON itself is valid (no extra commas, no Chinese quotation marks, etc.);
Confirm that every field name listed in required exists in properties;
$ref only supports the #/$defs/xxx form, and the referenced definitions must be placed in the top-level $defs.

​Overview

​JSON Schema format

​Basic structure

​Format detection

​Supported types

​Common patterns

​Unsupported keywords

​Automatic result correction

​Limits

​Schema validation tool

​Troubleshooting