API Documentation
Schema Documentation
Schema Best Practices
Creating effective JSON schemas is key to getting accurate and structured data from the AI. Follow these best practices to maximize the quality of your extracted data.
Use Clear Descriptions
Always include detailed descriptions for each property in your schema. These descriptions help the AI understand what information to look for in the input text.
⛔ Not Recommended:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
}
}✅ Recommended:
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The person's full name"
},
"age": {
"type": "number",
"description": "The person's age in years"
}
}
}Pro Tip:
Include units of measurement in your descriptions when applicable (e.g., "age in years", "height in centimeters", "weight in kilograms").
Use Descriptive Property Names
Choose property names that clearly reflect the data they represent. This makes your schema more understandable and helps the AI match data more accurately.
⛔ Not Recommended:
{
"properties": {
"fn": { "type": "string" },
"ln": { "type": "string" },
"dob": { "type": "string" }
}
}✅ Recommended:
{
"properties": {
"firstName": { "type": "string" },
"lastName": { "type": "string" },
"birthDate": { "type": "string" }
}
}Structure Your Schema Logically
Organize your schema to match the natural structure of the data. Group related properties using nested objects.
⛔ Not Recommended:
{
"properties": {
"name": { "type": "string" },
"streetAddress": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" },
"zipCode": { "type": "string" },
"country": { "type": "string" }
}
}✅ Recommended:
{
"properties": {
"name": { "type": "string" },
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" },
"zipCode": { "type": "string" },
"country": { "type": "string" }
}
}
}
}Be Specific with Types
Use the most specific type possible for each property. This helps the AI extract and format the data correctly.
⛔ Not Recommended:
{
"properties": {
"age": { "type": "string" },
"isActive": { "type": "string" },
"registrationDate": { "type": "string" }
}
}✅ Recommended:
{
"properties": {
"age": { "type": "number" },
"isActive": { "type": "boolean" },
"registrationDate": {
"type": "string",
"format": "date"
}
}
}Use Constraints Wisely
Add appropriate constraints to guide the AI in extracting valid data, but avoid making the schema too restrictive.
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2
},
"age": {
"type": "number",
"minimum": 0,
"maximum": 120
},
"email": {
"type": "string",
"format": "email"
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 5
}
}
}Note:
Constraints like minimum, maximum, minLength, etc., provide helpful hints to the AI, but making them too strict may cause the AI to reject valid data.
Be Selective with Required Properties
Only mark properties as required when they are truly necessary. This gives the AI more flexibility when extracting data from varied text inputs.
⛔ Not Recommended:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"phone": { "type": "string" },
"address": { "type": "string" },
"birthDate": { "type": "string" }
},
"required": [
"name", "email", "phone",
"address", "birthDate"
]
}✅ Recommended:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"phone": { "type": "string" },
"address": { "type": "string" },
"birthDate": { "type": "string" }
},
"required": ["name"]
}Pro Tip:
Consider using default values for properties that are optional but should have a fallback value when not found in the text.
Use Enums for Known Values
When a property can only have a specific set of values, use enums to constrain the possibilities and improve accuracy.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"orderStatus": {
"type": "string",
"enum": [
"pending",
"processing",
"shipped",
"delivered",
"cancelled"
],
"description": "The current status of the order"
},
"paymentMethod": {
"type": "string",
"enum": [
"credit_card",
"paypal",
"bank_transfer",
"crypto"
],
"description": "The payment method used for the order"
}
}
}Test Your Schema with Various Inputs
Always test your schema with different types of input text to ensure it extracts data correctly in various scenarios.
Here are some testing best practices:
- Test with both brief and detailed input text
- Test with text that contains all the information you're trying to extract
- Test with text that's missing some of the information
- Test with text that presents the information in different formats or orders
- Test with text that contains irrelevant information
Pro Tip:
Use the JSON Anything Playground to quickly test and refine your schemas with different input text samples.
Complex Example with Best Practices
Here's a comprehensive example that follows all the best practices:
{
"type": "object",
"properties": {
"product": {
"type": "object",
"description": "Product information",
"properties": {
"name": {
"type": "string",
"description": "The product name",
"minLength": 2
},
"sku": {
"type": "string",
"description": "Product SKU (Stock Keeping Unit) code",
"pattern": "^[A-Z]{2}-\d{4}$"
},
"price": {
"type": "number",
"description": "The product price in USD",
"minimum": 0
},
"category": {
"type": "string",
"description": "The product category",
"enum": ["electronics", "clothing", "home", "food", "toys", "other"]
},
"availability": {
"type": "boolean",
"description": "Whether the product is currently in stock",
"default": true
}
},
"required": ["name", "price"]
},
"customer": {
"type": "object",
"description": "Customer information",
"properties": {
"name": {
"type": "string",
"description": "Customer's full name"
},
"email": {
"type": "string",
"description": "Customer's email address",
"format": "email"
},
"shippingAddress": {
"type": "object",
"description": "Shipping address details",
"properties": {
"street": {
"type": "string",
"description": "Street address including house/apartment number"
},
"city": {
"type": "string",
"description": "City name"
},
"state": {
"type": "string",
"description": "State or province"
},
"zipCode": {
"type": "string",
"description": "Postal or ZIP code"
},
"country": {
"type": "string",
"description": "Country name",
"default": "United States"
}
},
"required": ["street", "city"]
}
},
"required": ["name"]
},
"orderDetails": {
"type": "object",
"description": "Order-specific details",
"properties": {
"orderId": {
"type": "string",
"description": "Unique order identifier"
},
"orderDate": {
"type": "string",
"description": "Date when order was placed",
"format": "date"
},
"quantity": {
"type": "number",
"description": "Number of product units ordered",
"minimum": 1,
"default": 1
},
"shippingMethod": {
"type": "string",
"description": "Selected shipping method",
"enum": ["standard", "express", "overnight"],
"default": "standard"
},
"specialInstructions": {
"type": "string",
"description": "Any special instructions for the order"
}
}
}
},
"required": ["product"]
}Example Input:
Order #ORD-1234 placed on November 23, 2023 by Jane Smith (email: [email protected]). Jane ordered 2 units of the Premium Wireless Headphones (SKU: EL-5678) for $129.99 each. The headphones are in the electronics category and currently in stock. The order will be shipped via express shipping to 123 Main St, Seattle, WA 98101. Special instructions: Please leave the package at the front door if no one answers.
Example Output:
{
"product": {
"name": "Premium Wireless Headphones",
"sku": "EL-5678",
"price": 129.99,
"category": "electronics",
"availability": true
},
"customer": {
"name": "Jane Smith",
"email": "[email protected]",
"shippingAddress": {
"street": "123 Main St",
"city": "Seattle",
"state": "WA",
"zipCode": "98101",
"country": "United States"
}
},
"orderDetails": {
"orderId": "ORD-1234",
"orderDate": "2023-11-23",
"quantity": 2,
"shippingMethod": "express",
"specialInstructions": "Please leave the package at the front door if no one answers."
}
}