How to write an extraction schema
How to write an extraction schema: describe columns in plain English, pick types like verbatim-string or enum, and avoid pitfalls that empty a column.
Columns
A schema is a list of columns. Each has a name, which becomes the JSON key, a type, and a description, which is what the extraction actually reads. multiple sits beside the list and asks for many rows per video.
Descriptions do the work
Write the description as you would explain the column to a person who has not seen the video. Name the thing, then say how it is likely to be spoken about. A bare label gives the model almost nothing to go on, and it is the most common reason a column comes back empty or full of the wrong thing.
"price"
"The price the host says the item cost, including the currency if they mention it"
For a field with a loose, general name — a category rather than a specific fact — the same rule needs one more piece: say what should not match, since the video will usually mention other things in a similar way. This matters most for repeated-row fields, where a vague description gets tested against the whole video rather than one clear spot.
"gas stations mentioned"
"The name of a gas station or convenience store brand the host visits — not snacks, drinks, or fuel types mentioned along the way, just the store's own name"
Column types
A column can also declare a type. It changes two things: what the extraction is allowed to answer with, and what you get back in the JSON. Leave it off and the first column is verbatim-string and the rest are string, which is what most schemas want.
These are the type names our specialized extraction model is trained on. It reads a typed template, and the names you write here go into it directly — so what you set and what the model is told are the same word.
Copied from the transcript word for word. The default for the first column, and what a name, a title or a quote wants.
Answered in the model's own words. The default for every column after the first — summaries, explanations, anything paraphrased.
Comes back as a number rather than a string. A figure the video never says is left null.
true or false, for a yes-or-no question about the video.
A date the narration mentions.
The answer has to be one of the options you list. Use it for a fixed vocabulary — a sentiment, a verdict, a category — so rows stay comparable across videos.
verbatim-string and the number types are checked against the transcript: a value that does not appear there is dropped rather than returned. That is the point of them — it is how a name or a figure comes back as something the video actually said, instead of something that sounds right.
Sending a template instead
Those columns compile to a typed JSON template, and that template is what the model is given. If you would rather write the template yourself, send it directly instead of columns — with a descriptions object alongside it, because a template carries types and not meanings. Both forms are stored the same way and run the same job.
The schema editor shows the compiled template live while you type, and will take a pasted one and turn it back into columns.
One row or many
Leave multiple off and you get one flat object describing the video as a whole. Set it to true and you get an array, one record per subject the narration covers. Use it when the video walks through several of something and each needs its own row.
A wide ask on a long video can return more rows than you want — "every reaction the host gives" can be a row a sentence. Set max_rows alongside multiple to keep the first rows found and drop the rest.
Several values in one column
multiple on the schema decides how many rows a video produces. multiple on a column is different: that column holds a list of values inside each row, and comes back as a real JSON array. Use it when one row naturally owns several of something — every dish ordered at one restaurant.
The template form writes the same thing as an array around the type: {"restaurants": [{"restaurant_name": "verbatim-string", "dishes": ["string"]}]}. Each time the restaurant comes up in the video it gets its own row, with the dishes said there, so you can combine or count them however you need.
enum column cannot either. Both are refused with a 400 when you submit.Pitfalls
Anything only visible on screen is invisible to us. If the narration never says it, no description will retrieve it.
A schema can hold 12 columns, but the more it asks at once, the more fields start borrowing from each other. If a wide schema gets muddled, run two narrower ones instead.
With a single-column array schema we split comma-separated runs back apart automatically. With two or more columns we cannot, because there is no reliable way to know which piece of one column matches which piece of another.
A field described only as "gas stations mentioned" also catches snack brands, fuel types, and other nearby nouns the narration happens to use the same way. Say what does not count, not just what does — one short sentence naming the kind of thing to exclude is usually enough to fix it.
A description is not something to keep adding clauses to. Past a certain point, a long list of definitions and exceptions crowds out the instruction that actually matters and the field gets messier, not cleaner. State the one or two things that matter and stop.