Add Annotation Questions

Overview

The Labellerr SDK uses Pydantic schemas to define annotation questions. Use the AnnotationQuestion schema to create type-safe questions for object-based annotations (bounding boxes, polygons, etc.) and classification workflows (dropdowns, radio buttons, etc.).

Required Question Structure

Using AnnotationQuestion Schema

Every question must be defined using the AnnotationQuestion schema with the following fields:

Field	Type	Required	Description
`question_number`	`int`	Yes	Sequential number for the question (1, 2, 3, …)
`question_id`	`str`	Yes	Unique identifier (UUID) - generate with `str(uuid.uuid4())`
`question`	`str`	Yes	The user-facing label or prompt
`question_type`	`QuestionType`	Yes	Enum value (e.g., `QuestionType.polygon`, `QuestionType.dropdown`)
`required`	`bool`	Yes	Set to `True` if the annotator must answer
`color`	`str`	Conditional	Required for object types (bounding_box, polygon, polyline, dot)
`options`	`List[Option]`	Conditional	Required for classification types (dropdown, radio, select, boolean)

Object-based questions (bounding_box, polygon, polyline, dot) require a color parameter (hex code).Classification questions (dropdown, radio, select, boolean) require options as a list of Option objects.Input questions don’t require either color or options.

Question Types Reference

Available Question Types

Object-Based Annotations:

QuestionType.bounding_box - Rectangle annotations
QuestionType.polygon - Multi-point polygon shapes
QuestionType.polyline - Connected line segments
QuestionType.dot - Single point markers

Classification Annotations:

QuestionType.dropdown - Single selection dropdown
QuestionType.radio - Radio button selection
QuestionType.select - Multi-select options
QuestionType.boolean - Yes/No toggle
QuestionType.input - Free text input

Specialized:

QuestionType.stt - Speech-to-text
QuestionType.imc - Image classification

Examples

Multiple Questions Template

Create a template with multiple question types including object detection and classification:

from labellerr.client import LabellerrClient
from labellerr.core.annotation_templates import create_template
from labellerr.core.schemas import (
    CreateTemplateParams,
    AnnotationQuestion,
    QuestionType,
    Option,
    DatasetDataType
)
import uuid

# Initialize client
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# Define questions using schema
questions = [
    AnnotationQuestion(
        question_number=1,
        question="Draw crop boundary",
        question_type=QuestionType.polygon,
        required=True,
        question_id=str(uuid.uuid4()),
        color="#5F9EA0"  # Hex color for object types
    ),
    AnnotationQuestion(
        question_number=2,
        question="Mark vehicle",
        question_type=QuestionType.bounding_box,
        required=True,
        question_id=str(uuid.uuid4()),
        color="#FFAA00"
    ),
    AnnotationQuestion(
        question_number=3,
        question="Overall quality",
        question_type=QuestionType.radio,
        required=True,
        question_id=str(uuid.uuid4()),
        options=[
            Option(option_name="Good"),
            Option(option_name="Average"),
            Option(option_name="Poor")
        ]
    ),
    AnnotationQuestion(
        question_number=4,
        question="Additional remarks",
        question_type=QuestionType.input,
        required=False,
        question_id=str(uuid.uuid4())
    )
]

# Create template
template = create_template(
    client=client,
    params=CreateTemplateParams(
        template_name="Demo Template",
        data_type=DatasetDataType.image,
        questions=questions
    )
)

print(f"Template created: {template.annotation_template_id}")

Single Question Template

Create a simple template with a single annotation question:

from labellerr.client import LabellerrClient
from labellerr.core.annotation_templates import create_template
from labellerr.core.schemas import (
    CreateTemplateParams,
    AnnotationQuestion,
    QuestionType,
    DatasetDataType
)
import uuid

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

questions = [
    AnnotationQuestion(
        question_number=1,
        question="Track object across frames",
        question_type=QuestionType.polygon,
        required=True,
        question_id=str(uuid.uuid4()),
        color="#FE1236"
    )
]

template = create_template(
    client=client,
    params=CreateTemplateParams(
        template_name="Video Tracking Template",
        data_type=DatasetDataType.video,
        questions=questions
    )
)

print(f"Template created: {template.annotation_template_id}")

Classification Only Template

Create a template with only classification questions (no object detection):

from labellerr.client import LabellerrClient
from labellerr.core.annotation_templates import create_template
from labellerr.core.schemas import (
    CreateTemplateParams,
    AnnotationQuestion,
    QuestionType,
    Option,
    DatasetDataType
)
import uuid

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

questions = [
    AnnotationQuestion(
        question_number=1,
        question="Image category",
        question_type=QuestionType.dropdown,
        required=True,
        question_id=str(uuid.uuid4()),
        options=[
            Option(option_name="Nature"),
            Option(option_name="Urban"),
            Option(option_name="Portrait")
        ]
    ),
    AnnotationQuestion(
        question_number=2,
        question="Contains people?",
        question_type=QuestionType.boolean,
        required=True,
        question_id=str(uuid.uuid4()),
        options=[
            Option(option_name="Yes"),
            Option(option_name="No")
        ]
    ),
    AnnotationQuestion(
        question_number=3,
        question="Tags",
        question_type=QuestionType.select,
        required=False,
        question_id=str(uuid.uuid4()),
        options=[
            Option(option_name="Outdoor"),
            Option(option_name="Indoor"),
            Option(option_name="Daytime"),
            Option(option_name="Nighttime")
        ]
    )
]

template = create_template(
    client=client,
    params=CreateTemplateParams(
        template_name="Image Classification Template",
        data_type=DatasetDataType.image,
        questions=questions
    )
)

print(f"Template created: {template.annotation_template_id}")

Best Practices

Unique Question IDs

Always generate unique question IDs using str(uuid.uuid4()) to avoid conflicts. Reuse IDs only when intentionally updating an existing question.

Sequential Numbering

Ensure question_number values are sequential (1, 2, 3, …) to maintain proper ordering in the annotation interface.

Color Selection

Use distinct hex colors for different object types to make them easily distinguishable in the annotation interface.

Clear Labels

Write concise, descriptive question text that clearly communicates what annotators should label.

Create Projects

Learn how to create projects using annotation templates

SDK Documentation

MCP Server

Overview

Required Question Structure

Using AnnotationQuestion Schema

Question Types Reference

Examples

Multiple Questions Template

Single Question Template

Classification Only Template

Best Practices

Unique Question IDs

Sequential Numbering

Color Selection

Clear Labels

Create Projects

Overview

​Required Question Structure

Using AnnotationQuestion Schema

​Question Types Reference

​Examples

Multiple Questions Template

Single Question Template

Classification Only Template

​Best Practices

Unique Question IDs

Sequential Numbering

Color Selection

Clear Labels

​Related Documentation

Create Projects

Required Question Structure

Question Types Reference

Examples

Best Practices

Related Documentation