> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/ontologies/classes-and-annotation-types.md).

# Classes and annotation types

A class names the concept; the annotation type defines how that concept is expressed. Choose the representation that the downstream model, analysis, or quality decision actually requires.

### Before you make the change

* Write the decision the label must support.
* Collect positive, negative, borderline, and invalid examples.
* Identify every modality and editor in which the class will appear.

![Ontology builder class configuration](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FH7BipjdCSKnZXmzpu8s4%2Fontology-builder.png?alt=media\&token=e88eadbf-aab2-41bc-a67b-46eb2cc58d82)

*Class names, descriptions, colors, hotkeys, annotation types, and required state should form one understandable operator experience.*

### Understand the product behavior

**Workbench ontology entities:**

* item properties: single-choice, multi-choice, text;
* spatial classes: bounding box, cuboid, polygon, mask, keypoint, line, skeleton;
* text entity;
* audio event;
* relation.

**SDK ontology structures:**

* shapes: bounding box, polygon, point, skeleton, polyline, bitmask, cuboid, time range, text;
* attributes: radio, checklist, text, numeric;
* whole-item/global classification;
* required attributes;
* dynamic attributes for values that can change across video keyframes;
* conditional attributes nested beneath selected options.

The UI and SDK use slightly different vocabulary for closely related concepts—for example Mask/bitmask, Event/time range, Entity/text, single-choice/radio, and multi-choice/checklist.

### Class configuration

A class can include:

* name;
* description;
* color;
* numeric hotkey;
* geometry;
* attributes/properties;
* single-select, multi-select, and text properties;
* relations.

Geometry is selected when the class is created and is read-only afterward. This prevents an existing class from silently changing from one annotation representation to another. The class summary shows the stable class ID, description, color, hotkey, geometry, required state, thumbnails, statistics, maximum property depth, logic map, and JSON export.

### Define the top-level schema

{% stepper %}
{% step %}

#### 1. Name the concept

Use a stable domain term with a precise description and examples.
{% endstep %}

{% step %}

#### 2. Choose annotation types

Select classification, bounding box, polygon, mask, line, keypoint, relation, segment, span, or other current representation as required.
{% endstep %}

{% step %}

#### 3. Configure operator cues

Set color, hotkey, ordering, and required state to reduce ambiguity in Workbench.
{% endstep %}

{% step %}

#### 4. Add only meaningful structure

Avoid classes or geometry that do not change downstream interpretation.
{% endstep %}

{% step %}

#### 5. Test in each native editor

Confirm the class behaves correctly for every attached modality and layout.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision       | Production guidance                                                                          |
| -------------- | -------------------------------------------------------------------------------------------- |
| Class scope    | Prefer a coherent reusable concept over project-specific wording when the meaning is stable. |
| Geometry       | Use the minimum representation that preserves the required downstream information.           |
| Required state | Make only true acceptance requirements mandatory.                                            |
| Change         | Treat renamed, removed, or retyped concepts as schema changes with migration impact.         |

### Continue the operating flow

* Add typed properties and relations.
* Define Item Properties for work-unit outputs.
* Test the complete ontology before publishing.