Writing a schema
The schema is the whole interface. Getting the descriptions right is the difference between usable rows and empty ones.
Columns
A schema is a list of columns. Each has a name, which becomes the JSON key, and a description, which is what the extraction actually reads.
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 description costs a great deal of accuracy; in our own testing, going from terse labels to full sentences moved field accuracy from roughly a third to most of the way.
"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 NuExtract 3.0's own type names, not ours. The extraction model reads a typed template, and the names you write here are the names that go into it — 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 NuExtract template instead
Those columns compile to a NuExtract 3.0 template, and that template is what the model is given. If you already work in that format you can send it directly instead of writing 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.
Pitfalls
Anything only visible on screen is invisible to us. If the narration never says it, no description will retrieve it.
Six or seven columns per schema is a comfortable ceiling. Beyond that, fields start borrowing from each other. Run two narrower schemas 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, in our own testing, a long list of definitions and exceptions crowded out the instruction that actually mattered and the field got messier, not cleaner. State the one or two things that matter and stop.