Label types & values

A label has one of five types. The type fixes the settings it needs and the control an annotator sees. Every submitted answer is written into the label’s score as JSON, in Score.value, and this page shows the shape that value takes for each type, plus the checks re-applied when a value is submitted. For which type to pick, see Labels; for the steps to create one, see Create a label.

Every setting listed below is required by the backend; there’s no default value for any of them. The prefills shown in each table are what the create drawer fills in for you, not defaults the API falls back to.

Categorical

Setting	What it does	Constraint	Create drawer prefills
options	The list of options the annotator picks from, each an object with a label field, for example [{"label": "Good"}, {"label": "Needs work"}]	Two or more, each non-empty, and unique once case differences are ignored	Required, no default
multi_choice	Whether the annotator can pick more than one option	None	false (single choice)

Creating a categorical label also requires additional auto-annotation settings: rule_prompt, auto_annotate, and strategy.

The annotator picks from the options you defined, one or several depending on multi_choice. The stored value is always an object with a selected array of the picked option labels: a single-select answer holds one label, for example {"selected": ["Good"]}; a multi-select answer holds more than one, for example {"selected": ["Good", "Needs work"]}.

Numeric

Setting	What it does	Constraint	Create drawer prefills
min	The lowest value on the range	0 or greater	0
max	The highest value on the range	0 or greater, and greater than min	10
step_size	The increment between values the annotator can land on	Greater than 0	1
display_type	Whether the annotator sees a slider or a row of buttons	slider or button	slider

The annotator sees a slider or a row of buttons, depending on display_type, stepping from min to max in step_size increments. The chosen value is stored as {"value": 7.5}.

Text

Setting	What it does	Constraint	Create drawer prefills
placeholder	Placeholder text shown in the empty field	None	Enter your feedback...
min_length / max_length	The minimum and maximum length allowed for the submitted text	min_length must be less than max_length	0 / 500

The annotator gets a free-text field showing placeholder when empty. The entered value is stored as {"text": "Needs a citation for the second claim"}.

Star Rating

Setting	What it does	Constraint	Create drawer prefills
no_of_stars	How many stars the annotator sees	Greater than 0; the create drawer caps it at 10, though the backend has no upper bound	5

The annotator sees a row of no_of_stars stars to tap. The number of stars picked is stored as {"rating": 4}.

Thumbs Up/Down

No settings beyond the type itself.

The annotator sees a thumbs up / thumbs down toggle. The pick is stored as {"value": "up"} or {"value": "down"}.

Checks applied on submit

Every value is checked again against the label’s settings when it’s submitted, not just when the label is created:

• Categorical: every selected option must be one you defined, and if multi_choice is off, only one option can be selected
• Numeric: the value must fall within [min, max], and must land on a step_size increment unless it’s exactly max
• Text: the value’s length must fall within [min_length, max_length]
• Star Rating: the value must be a whole number between 1 and no_of_stars
• Thumbs Up/Down: the value must be up or down

Keep exploring