> 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/properties-relations-and-item-properties.md).

# Properties, relations, and Item Properties

Properties, relations, and Item Properties all become annotation output, but they attach to different owners. Decide the owner first; then choose type, required state, dynamic behavior, validation, conditions, and operator guidance.

### Choose the correct structure

| Structure       | Attach it to                                              | Use it for                                                    | Example                                   |
| --------------- | --------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- |
| Property        | One annotation object or span.                            | Structured detail about that instance.                        | Person → Helmet status.                   |
| Relation        | Two or more annotation instances.                         | A named semantic connection with defined targets.             | Person → operates → Forklift.             |
| Item Property   | The full asset, sequence, document, study, or Data Group. | Whole-item annotation output independent of one object.       | Scene → Weather; Study → Overall quality. |
| Source metadata | The source resource outside annotation output.            | Acquisition or business context used to find or prepare data. | Camera ID, source path, acquisition date. |

### Path 1: create schema content in the Ontology builder

![Ontology entity-type menu with Item Properties, object detection, text, audio, and relation types](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FJwNKpXsKwqxWM4RkOYmM%2Fontology-entity-types.png?alt=media\&token=ffe784be-db31-4844-a48d-86f171450971)

*Select the entity type before naming a new class, Item Property, event, entity, or relation. The available groups reflect the supported annotation structures.*

1. Open the workspace ontology or the project's ontology.
2. Open **Select type** in the entity tree.
3. Choose an Item Property type, an object-detection geometry, a text **Entity**, an audio **Event**, or **Relation**.
4. Enter the new entity name and choose the add action.
5. Select the resulting class or property in the tree.
6. For a class, use **Add Property** in the schema canvas; choose Single choice, Multiple choice, or Text and the scalar type needed by the contract.
7. Add description, options, Required state, Dynamic state where supported, default value, validation, help text, and conditional dependency.
8. Review Summary, JSON, statistics, and Logic Map before testing in Workbench.

Object-detection options include Bounding box, Cuboid, Polygon, Mask, Keypoint, Line, and Skeleton. Geometry is part of the class contract; do not change representation simply because another tool is faster.

### Build properties and conditional children

![Ontology with three levels of conditional single-choice properties](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F5WGTh7i4QrEJfLGt2ZjV%2Fontology-nested-properties.png?alt=media\&token=03c67080-6bdb-4616-a711-8e3b8a50b5e8)

*The builder shows the parent option, WHEN condition, child property, and deeper child branch directly in the schema canvas.*

Use controlled choice properties for stable enumerations and Text for string, number, boolean, date, datetime, URL, email, or object-ID values supported by the current builder. A child property belongs beneath the parent option that makes it relevant. The illustrated schema asks a second question when **Bottle** is selected, then asks for a glass color only when **Glass** is selected.

Deep conditional nesting is supported, but every branch adds operator and downstream complexity. Keep only questions that change meaning or acceptance.

### Path 2: extend the ontology from Annotation Workbench

![Image Annotation Workbench with Classes panel and item-level controls](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FXDWBnDB8WFTU6efWwzzN%2Fworkbench-classes-item-properties.png?alt=media\&token=6689950e-874b-493e-bba4-0bc8729fd62f)

*Workbench exposes the active project's classes beside the source item so ontology changes can be tested in the same operator context in which they will be used.*

Workbench provides two levels of schema authoring:

#### Quick class and class management

* Use **Quick Create Class** when a compatible class is missing for the active editor.
* Open the class-management entry and choose **Manage Classes** for the lightweight manager.
* Select the annotation type, search for an existing class or create one, and choose **Add**.
* Configure name, color, description, Required state, and hotkey. Geometry remains fixed after creation.
* Use the same manager to create lightweight Item Properties and relations.
* Choose **Manage Ontologies** when the complete builder, JSON, logic map, versions, or advanced schema controls are required; Unitlab opens the full builder in a new tab.

#### Add a property from an annotation object

1. Create or select an annotation object in Workbench.
2. In the object inspector, choose **Add property**.
3. Enter name and description.
4. Set **Required** and, for supported video or medical work, **Dynamic**.
5. Choose the property type and scalar type, then configure options where applicable.
6. Choose **Add property**, set the value on the selected object, and inspect the result in the timeline when Dynamic is enabled.

#### Add a relation

Select an object, choose **Add relation**, name and describe the relation, define the allowed target classes, save it, then create the relationship between the intended source and target annotations. Test direction and target restrictions; a relation label without direction is ambiguous downstream.

#### Add an Item Property

Open **Item properties** at the top of the inspector, choose **Add item properties**, enter name and description, configure Required and Dynamic, choose the type and options, then add and set the value. Item Properties are independent of one annotation object.

### Static and Dynamic properties

A static property applies one value to the object or item. In video and medical annotation, a Dynamic property stores frame-aware states while the owning identity remains the same.

* **Dynamic class-property example:** one Person track keeps the same identity while Helmet status changes from Not visible to Present to Absent.
* **Dynamic Item Property example:** the sequence-level Weather changes from Clear to Rain, or Procedure phase changes from Preparation to Inspection.

In Workbench, the first value creates a keyframe or range. Changing the value later creates another state. Expand the parent object or Item Property row in the timeline to inspect child property ranges and transition points; adjust temporal boundaries only after reviewing the source frames.

{% hint style="warning" %}
For an existing property, the Dynamic switch can be locked. When the product requires recreation, assess the schema and historical-label impact before deleting and rebuilding the property.
{% endhint %}

### Before publishing

* confirm every field owner, type, ID, default, help text, Required state, Dynamic state, validation, and condition;
* traverse every nested branch in Workbench;
* create representative relations and verify source, target, and direction;
* inspect static and dynamic Item Properties in the correct editor;
* compare JSON and sample release output to the downstream schema.