Yes. A webpage becomes JSON that matches a schema by one of three routes: read the structured data the page already carries, map CSS or XPath selectors to your fields, or describe the shape you want and let an extractor fill it. Each one holds up on a different kind of page, and every one of them needs a validation step at the end.
This post compares the three, shows the third route as a single Python call, and spells out what you get back when a page does not have a field.
The three routes, side by side
| Route | Holds up when | Breaks when | What you maintain |
|---|---|---|---|
| Read the page’s own JSON-LD or microdata | The site publishes schema.org markup and your target is close to it (Product, Article, JobPosting) | The markup is missing, partial, or stale, or your schema is not schema.org | A mapping from their fields to yours |
| Map selectors to fields | The pages come from one template you control or know well | The layout changes, the content is rendered by JavaScript, or you add a second site | One selector per field, per site |
| Describe the shape, let an extractor fill it | The pages vary, the fields are visible to a reader, and you want one contract across many sources | The field you want is a judgment, not a fact on the page | The schema and its descriptions |
The first two are deterministic and cheap; use them when they fit. The third holds one schema across many sites, and it is where this post spends the most time.
Route 1: read the structured data the page already has
Many pages embed schema.org data as JSON-LD, Microdata, or RDFa. If the site publishes it and your schema is close to the schema.org type, parse it out and map the fields. In Python, extruct pulls all three formats from HTML. There is no model involved and nothing to guess.
The catch is coverage. Sites publish JSON-LD for the fields that help their search listing, not for the fields you need, and the markup can lag the visible page. Use it as a first source and fill the gaps another way.
Route 2: map selectors to your fields
If every page comes from one template, CSS or XPath selectors that map page elements to your schema’s fields are fast to write, easy to test, and free to run. BeautifulSoup, lxml, Scrapy, and Cheerio all do this well.
Selectors break the day the layout changes, and they need a headless browser the moment the content is rendered by JavaScript. They also do not travel: a second site means a second set. For a handful of stable sources they are the right call. For a list of sources you do not control, you maintain a selector set per site and repair it each time a layout changes.
Route 3: describe the shape and let an extractor fill it
The third route is to send the page and a JSON schema to something that reads the page and returns an object in that shape. You can build this yourself: fetch the HTML, render it if you have to, strip the chrome, call a model with structured outputs, parse, validate, retry. Or you can make it one call and keep that pipeline out of your application.
Tabstack Extract is the one-call version. You pass a URL and a JSON schema to /extract/json. Fetching, rendering when the page needs a browser, locating each field, and shaping the output to the schema happen inside the call. What comes back is JSON with the keys and types you declared.
import json
import jsonschema
import tabstack
from tabstack import Tabstack
SCHEMA = {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Product name as shown in the page heading.",
},
"price": {
"type": ["number", "null"],
"description": "Current price as a number with no currency symbol, "
"not a crossed-out or original price. Null if the page shows no price.",
},
"currency": {
"type": ["string", "null"],
"description": "ISO 4217 code for the price, such as USD. Null if no price is shown.",
},
"in_stock": {
"type": ["boolean", "null"],
"description": "True if the page says the item can be bought now, "
"false if it says sold out or unavailable, null if the page does not say.",
},
},
"required": ["name"],
}
client = Tabstack() # reads TABSTACK_API_KEY from the environment
try:
data = client.extract.json(
url="https://www.ifixit.com/products/pro-tech-toolkit",
json_schema=SCHEMA,
)
except tabstack.APIError as err:
raise SystemExit(f"Extract call failed: {err}")
try:
# Shape check: raises if a key or type is off.
jsonschema.validate(instance=data, schema=SCHEMA)
except jsonschema.ValidationError as err:
raise SystemExit(f"Response does not match the schema: {err.message}")
print(json.dumps(data, indent=2))
On that product page, the call returned:
{
"currency": "USD",
"in_stock": true,
"name": "Pro Tech Toolkit",
"price": 79.95
}
Two parts of that snippet matter most.
The descriptions are instructions. Without them the extractor has only the property name to go on, and price on a product page can mean the sale price, the list price, or the per-unit price. The description on price above is the difference between the current number and the struck-through one. Start with a plain schema, run it, and add descriptions to the fields that come back wrong. The schema design guide goes deeper on writing them.
The validation step is yours. Tabstack shapes the response to your schema, and your pipeline should still check it on the way in. jsonschema.validate raises on a wrong key or type, so a bad row stops there instead of reaching your database. Pydantic works as well if you already model your data that way.
What you get when the page does not have a field
A Tabstack Extract call does not fail because the page lacked your data. You get a 200 and an object shaped like your schema. What lands in a field the extractor could not fill depends on whether you marked it required. This is the behavior observed against the live API, and documented in the schema design guide:
| Schema type | Optional field, absent from the page | Same field marked required |
|---|---|---|
| string | null or omitted | null |
| number | null or omitted | 0 |
| boolean | null or omitted | false |
| array | null, [], or omitted | [] |
| object | null or omitted | object present, leaves filled by the rules above |
So:
- Optional fields tell you when data is missing. Declare
["number", "null"], say in the description when null applies, and treat a missing key the same as null. - Required fields trade that signal for a value. A required number comes back
0and a required booleanfalseeven when the page never mentions them. Only mark a field required when you need a value in every row and can tell a placeholder from real data. - Validate values, not just keys. In the example above,
nameis a required string, so anullthere makesjsonschema.validateraise. A schema check cannot tell you the page was the wrong kind of page, though: pointed at a page with no product, the same call can fillnamewith the page heading and returnnullfor everything else, which passes validation. Check that the values make sense for the row, such as a price present when you expect one. - Test against a page you know is empty. Run the schema once on a URL that lacks the fields and record what each one returns, so your checks match real behavior rather than assumed behavior.
A schema with an unknown type keyword, say {"type": "banana"}, is accepted too. The call returns 200 with that field set to null, so a typo in a type looks like missing data. Test a new schema against a page you know well before running it at volume.
Where the page goes, and what happens to it
With routes 1 and 2 the page stays on your machine. With route 3 the request goes to whoever runs the extraction, a model provider you call yourself or a managed service, so check what happens on the other end.
With Tabstack, the URL and your schema go to the API, and the page is fetched and read outside your model and your application. Never trained on. Private by default. Built by Mozilla. An organization admin can turn off request-history collection in the console. See how data is handled.
How to pick
- The site publishes JSON-LD for the fields you need, and your schema is close to schema.org: read it directly and map the fields.
- A handful of sources on stable templates you can watch: selectors, with a headless browser only if the content is rendered client-side.
- Many sources, varied layouts, or one schema that has to hold across all of them: schema-guided extraction, either built yourself or as one call.
- The field you want is an interpretation (a summary, a category, “is this pricing aggressive”): extraction is the wrong tool. Use /generate/json, which puts a model in the loop on purpose and still returns your schema.
A common hybrid: parse any JSON-LD first, use selectors for the fields you know how to find, and send only the rest through an extractor. Validate the merged result against your schema either way.
Questions that come up
Does it work on JavaScript-rendered pages?
Yes. The effort parameter sets how the page is fetched: min is the fastest fetch with no fallback, standard is the default, and max renders the page in a full browser for pages that build their content with JavaScript. See Choosing an effort level.
Do I have to write selectors? No. The schema is the whole specification, and the HTML parsing happens inside the call.
Is the output validated against my schema? The response is shaped to your schema, with the types you declared. Validate it again in your own code, and validate values as well as keys, for the reasons in the missing-field table above.
What if I do not want to write the schema from scratch?
The schema library publishes ready-made extraction schemas by category, and the CLI pulls one into a local store with tabstack schema pull job-posting. Treat a pulled schema as a first draft and adapt its descriptions to the site you are pointing it at.
Does one call crawl the site? No. One URL per call, no link following. For a list of pages, loop over them with the same schema; the job listings example shows the pattern.
Can I use my own model with this? Yes. Extract runs outside your model and returns a plain object. Pass it to a model you run yourself, a hosted one, or straight into your database.
Try it
pip install tabstack jsonschema
export TABSTACK_API_KEY="your-key"
Point the snippet above at a page you know, read what comes back, then add descriptions to whichever fields were wrong. Every new account includes 10,000 free credits with no card required, and an Extract JSON call uses 50. The How to Extract JSON guide has the same call in TypeScript, the CLI, and curl.



