Guides/Writing a schema

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.

{
"multiple": true,
"columns": [
{
"name": "restaurant_name",
"description": "Name of the restaurant, diner or food spot the host visited"
},
{
"name": "food_ordered",
"description": "What food or dish the host said he ate or ordered there"
}
]
}

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.

Weak

"price"

Better

"The price the host says the item cost, including the currency if they mention it"

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.

NOTE
A saved schema is versioned, and a job records the version it ran. Editing publishes a new version rather than changing the old one — otherwise a finished job would start describing work it never did.

Pitfalls

Asking for what is shown, not said

Anything only visible on screen is invisible to us. If the narration never says it, no description will retrieve it.

Too many columns at once

Six or seven columns per schema is a comfortable ceiling. Beyond that, fields start borrowing from each other. Run two narrower schemas instead.

Several values crammed into one field

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.

Was this page useful?Tell us what was missing