Schema Design for Accurate Extraction

The schema you pass to /extract/json and /generate/json is the most important factor in extraction quality. It’s not just a shape definition; it’s a set of instructions for the AI doing the extraction.

This guide covers the patterns that produce reliable results and the common mistakes that produce noise.

---

Descriptions are instructions, not documentation

Every property description you add tells the extraction AI what to look for and how to interpret it. Without descriptions, the AI has only the property name to go on, and names are ambiguous.

TypeScript

// Ambiguous: AI guesses what 'price' means
json_schema: {
  type: 'object',
  properties: {
    price: { type: 'number' }
  }
}

// Specific: AI knows exactly what to extract
json_schema: {
  type: 'object',
  properties: {
    price: {
      type: 'number',
      description: 'Monthly price in USD as a number. Null if pricing requires contacting sales.'
    }
  }
}

Python

# Ambiguous: AI guesses what 'price' means
json_schema = {
    "type": "object",
    "properties": {
        "price": {"type": "number"},
    },
}

# Specific: AI knows exactly what to extract
json_schema = {
    "type": "object",
    "properties": {
        "price": {
            "type": "number",
            "description": "Monthly price in USD as a number. Null if pricing requires contacting sales.",
        },
    },
}

The second version extracts correctly even when the price is presented as "$49/mo", a range, or missing entirely. The description tells the AI how to handle each case.

---

Be explicit about null cases

Pages don’t always have every field. Tell the AI what to return when data is absent.

TypeScript

properties: {
  annual_discount: {
    type: ['number', 'null'],
    description: 'Percentage discount for annual billing (e.g. 20 for 20% off). Null if no annual option is offered.'
  },
  trial_days: {
    type: ['number', 'null'],
    description: 'Length of free trial in days. Null if no trial is available.'
  }
}

Python

"properties": {
    "annual_discount": {
        "type": ["number", "null"],
        "description": "Percentage discount for annual billing (e.g. 20 for 20% off). Null if no annual option is offered.",
    },
    "trial_days": {
        "type": ["number", "null"],
        "description": "Length of free trial in days. Null if no trial is available.",
    },
}

Declaring null in the type and describing when it applies is the strongest signal you can give the extractor. It is not a guarantee. Read the next section before you write validation logic against it.

---

What you get back when a field can’t be filled

This is the part to understand before you put /extract/json in a pipeline.

A call never fails because the page was missing your data. You get a 200 and an object shaped like your schema. There is no “no match” status, no partial-match flag, and no list of fields the extractor couldn’t fill. Marking a field required does not change that; it makes the extractor try harder, it does not make the call fail.

What lands in an unfillable field depends on its type. Observed against the live API on 2026-07-27:

Schema type	Field absent from the page	Same field marked required
string	null	""
number	0	-1
boolean	false	false
array	[]	[]
object	Object present, leaves filled by the rules above	Same

Absent strings are reliable. Absent numbers and booleans are not. A missing number comes back as a real number and a missing boolean as false, so neither is distinguishable from a genuine 0 or a genuine false.

That distinction is the whole risk. If your schema is mostly strings you will see clean nulls and never notice. Add one number field and you have a silent data-quality bug:

// founded_year comes back as 0 for a page that never mentioned a founding year
const age = 2026 - data.founded_year; // 2026, not "unknown"

// employee_count comes back as 0, so this row silently fails the filter
if (data.employee_count > 50) enrich(row);

Writing pipeline logic against this

• Validate values, don’t just null-check. Treat 0, -1, false, and "" as suspect for any field that could legitimately be absent from the page.
• Prefer ['number', 'null'] over number, and say in the description when null applies. It shifts the odds toward null; it does not remove the need to validate.
• Give absence its own field when a distinction actually matters to you. A has_pricing boolean the extractor can affirmatively set is more trustworthy than inferring absence from a 0 in price.
• Sanity-check against a known-empty page while building. Run your schema against a URL you know lacks the fields and record what each one returns, so your validation matches real behavior rather than assumed behavior.

Malformed requests

Schema problems and page problems fail differently:

Request	Response
json_schema omitted	400 { "error": "json_schema is required" }
json_schema isn’t a JSON object	400 { "error": "invalid JSON request body" }
json_schema contains an unknown type keyword	200, field returns null

The third row is worth noting: an invalid schema is not rejected. A typo like { "type": "banana" } returns 200 with null rather than a validation error, so a broken schema fails quietly on every call instead of loudly on the first. Test a new schema against a page you know well before running it at volume.

See Error Reference for the full error shape.

---

Match your schema depth to the page structure

If the page has a two-level hierarchy (categories containing products), your schema should reflect that:

TypeScript

json_schema: {
  type: 'object',
  properties: {
    categories: {
      type: 'array',
      description: 'Top-level product categories on the page',
      items: {
        type: 'object',
        properties: {
          name: { type