```yaml
product: AlterLab
title: JSON Schema Filtering
category: guides
comparison_context: "AlterLab is an alternative to Firecrawl, ScrapingBee, and Bright Data."
source_url: https://alterlab.io/docs/guides/json-schema-filtering
```

# JSON Schema Filtering

Filter and restructure already-extracted data to match your desired output format.

> JSON Schema filtering is **not LLM extraction**. It filters existing structured data (Schema.org, Open Graph, etc.) to match your desired schema. Zero additional cost.

## How It Works

1. **Automatic Extraction** -- AlterLab extracts structured data from the page using Schema.org, Open Graph, readability, and other sources
2. **Schema Matching** -- Your JSON Schema tells us which fields you want. We use exact matching, case-insensitive matching, field aliases, and nested search
3. **Type Coercion** -- Automatic type conversion (string to number, string to boolean) and price parsing ($99.99 to 99.99)
4. **Filtered Result** -- Clean response with only the fields you requested in `filtered_content`

## Basic Example

```bash
curl -X POST https://api.alterlab.io/api/v1/scrape \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/watch",
    "extraction_schema": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "price": {"type": "number"},
        "image": {"type": "string"},
        "available": {"type": "boolean"}
      }
    }
  }'
```

**Response:**

```json
{
  "success": true,
  "content": { "..." },
  "filtered_content": {
    "title": "Patek Philippe Calatrava",
    "price": 22500,
    "image": "https://example.com/watch.jpg",
    "available": true
  },
  "credits_used": 1
}
```

## Field Aliases

Schema filtering automatically handles common field name variations:

| Your Schema Field | Auto-Matched Source Fields |
|-------------------|--------------------------|
| `title` | name, product_name, productName, heading, headline |
| `price` | amount, value, cost, priceAmount |
| `image` | thumbnail, imageUrl, img, photo, picture, mainImage |
| `author` | writer, byline, authorName, creator |
| `published` | publishedAt, datePublished, date, publishDate |
| `available` | availability, inStock, in_stock, stock |
| `sku` | asin, productId, product_id, identifier, item_id |
| `image_urls` | images, imageUrls, photos, pictures, gallery |

**4-Level Matching Strategy:**
1. Exact match (case-sensitive)
2. Case-insensitive match
3. Aliases
4. Nested search (e.g., `jsonLd.price`)

## Type Coercion

- **String to Number**: `"$1,234.56"` becomes `1234.56`
- **String to Boolean**: `"in_stock"` / `"yes"` / `"1"` become `true`; `"out_of_stock"` / `"no"` / `"0"` become `false`
- **String to Integer**: `"42"` becomes `42`

If coercion fails, the original value is returned unchanged.

## Nested Objects & Arrays

```json
{
  "extraction_schema": {
    "type": "object",
    "properties": {
      "product": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "price": {"type": "number"}
        }
      }
    }
  }
}
```

For arrays:

```json
{
  "extraction_schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "price": {"type": "number"}
      }
    }
  }
}
```

## Selector Extraction (No LLM, No BYOK)

When you know the page layout, pass `extraction_selectors` on `/v1/scrape`, `/v1/extract` or batch. Selectors run deterministically on the fetched HTML and the result is returned as the `json` format.

```json
{
  "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
  "extraction_selectors": {
    "title": {"css": "div.product_main h1"},
    "price": {"css": "p.price_color"},
    "tags": {"xpath": "//ul[@class='breadcrumb']//a", "multiple": true},
    "image": {"css": "div.item img", "attr": "src"}
  }
}
```

Each spec takes exactly one of `css` or `xpath`, plus optional `attr` and `multiple`. Unmatched fields return `null` (`[]` when `multiple`); an invalid selector only nulls its own field.

## Profiles: Deterministic vs BYOK

| Profile | `/v1/scrape` | `/v1/extract` |
|---|---|---|
| `auto`, `product`, `article`, `job_posting`, `faq`, `recipe`, `event` | Deterministic, no LLM | LLM, requires BYOK key |
| All other profiles (e.g. `directory_listing`) | Not deterministic; treat as BYOK | LLM, requires BYOK key |

`GET /v1/extract/templates` returns `deterministic` and `requires_byok_on_extract` for each profile. Use `extraction_selectors` for key-less extraction on `/v1/extract`.

## Best Practices

1. **Use user-friendly field names** -- Aliases will find the right source field
2. **Always specify types** -- Enables automatic type conversion
3. **Handle missing fields** -- Not all fields will be present on every page
4. **Use the Playground** -- Test your schema at [alterlab.io/playground](https://alterlab.io/playground) before production
