Writing a schema

There are two ways to acquire a schema for universal information extraction:

1. Automatic schema generation (recommended)
2. Manual schema design.

Automatic schema generation

Manually defining a schema can be daunting and may require multiple trial-and-error attempts. The Schema Generation API helps you to create an initial schema from up to three sample files with ease.

The extracted schema is returned as a stringified JSON object within the message content. It adheres to the JSON Schema syntax and input schema restriction of the Information Extract API. User can provide their intention about the schema generation through the system message.

Try editing the extracted schema to better match your specific extraction needs before using it in the information extraction process.

import base64
import json
from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1/information-extraction/schema-generation"
)

def encode_img_to_base64(img_path):
    with open(img_path, 'rb') as img_file:
        img_bytes = img_file.read()
        base64_data = base64.b64encode(img_bytes).decode('utf-8')
        return base64_data

# Read the image file and encode it to base64
img_path = "./bank_statement.png"
base64_data = encode_img_to_base64(img_path)

# Schema generation request
schema_response = client.chat.completions.create(
    model="information-extract",
    messages=[
        {
            "role": "system",
            "content": "Generate schema about bank_name."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{base64_data}"}
                }
            ]
        }
    ],
)
schema = json.loads(schema_response.choices[0].message.content)

{
  "type": "json_schema",
  "json_schema": {
    "name": "document_schema",
    "schema": {
      "type": "object",
      "properties": {
        "bank_name": {
          "type": "string",
          "description": "The name of bank in bank statement."
        }
      }
    }
  }
}

Manual schema design

We recommend starting with automatic schema generation, but you can also manually define the schema or modify an automatically generated one.

Available datatypes

Schemas should follow the JSON Schema Syntax. The following types are supported for Schema:

• Note that the root object must be object type.
• Arrays: If you need to extract multiple values for the same key, you can use the array type. In {"type": "array"}, the "items" keyword must be specified to define the values.
• Objects: To define multiple properties under a key, you can use the object type. In {"type": "object"}, the "properties" keyword must follow to define the structure. Additionally, the object type can be used as the items of an array to represent table structures. An example is shown below:

  {
    "type": "object",
    "properties": {
      "transactions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "transaction_date": {
              "type": "string",
              "description": "Date on which each transaction occurred."
            },
            "transaction_description": {
              "type": "string",
              "description": "Description of each transaction."
            }
          }
        }
      }
    }
  }

Schema design best practices

• Use clear key names and descriptions: Providing clear and descriptive key names and descriptions significantly improves the accuracy of data extraction.
• Avoid vauge or overly generic key names: Use specific terms where applicable, and include concise descriptions that explain the purpose and expected values of each key.

Schema design restrictions

Note that when you manually design a schema, there are some restrictions involved.

• In a schema, total string length of all property names and definition names cannot exceed 10,000 characters.
• Up to 100 object properties and 15,000 characters are allowed in synchronous API.
• Up to 5000 object properties and 120,000 characters are allowed in asynchronous API.
• First-level properties must be of type string, integer, number, or array (object type is not permitted).

  {
    "type": "object",
    "properties": {
      "bank_name": {
        "type": "object",  # ❌ Object type properties are not allowed in the first-level
        "properties": {
            ...
        }
      }
    }
  }

• An array cannot contain items of arrays.

  {
    "type": "object",
    "properties": {
      "bank": {
        "type": "array",
        "items": { "type": "array", "items": {...}}  # ❌ Nested arrays are not allowed
      }
    }
  }