> 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/ontologies-overview.md).

# Ontologies overview

An ontology is Unitlab's versioned semantic contract for annotation. It defines classes, geometry or annotation type, instance properties, relations, Item Properties, required values, conditional questions, validation, operator guidance, and the schema that reaches releases and integrations.

### Start from the workspace ontology catalog

![Workspace Ontologies list with Live status and schema counts](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F5SPPXUzaE7ep9xPCoVzq%2Fontologies-list-live.png?alt=media\&token=8b258dd3-96a7-487e-b2d8-8345a4bb6d5c)

*The workspace catalog makes ontology identity, Live state, class/property/relation counts, update time, and row actions visible before an editor is opened.*

Open **Ontologies** from the workspace sidebar. Use the catalog to:

* search by ontology name;
* filter by lifecycle status;
* compare class, property, and relation counts;
* identify the current **Live** schemas;
* open row actions for an existing ontology;
* choose **New Ontology** to start a new workspace schema.

Treat names as human labels and IDs plus versions as the durable contract. Two ontologies can have the same display name while representing different resources or histories.

### Understand workspace, Global, and Project Ontologies

#### Project Ontologies

![Project Ontologies page with a Live ontology](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FjOjE1y7iPqXilO3mp6Qu%2Fproject-ontologies-current.png?alt=media\&token=1085aad6-b926-4e13-827c-dcecf81bd01d)

*A project can maintain several ontology copies, but only one is Live for active annotation at a time.*

Open a project and choose **Ontologies** to create, switch, and maintain the schemas owned by that project. Use the row action to make the intended copy Live after testing. Replacing the Live selection does not delete the previous ontology.

#### Global Ontologies

![Global Ontologies catalog opened from a project](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FKIDCx8TOBuPPZZI2OEeI%2Fproject-global-ontologies.png?alt=media\&token=0263d87e-19ce-48cc-86da-90d7363ccef4)

*Global Ontologies is the reusable workspace catalog. Importing a catalog ontology creates an independent project copy.*

From Project Ontologies, choose **Global Ontologies** to browse reusable schemas. Import the approved schema into the project, then review and test the resulting project copy. Import is not a permanent live-sync relationship: later global changes do not silently rewrite the project's contract.

Some teams call reusable catalog schemas public or shared ontologies. The current product surface uses **Global Ontologies**. Project Ontologies are the project-owned working copies used for project annotation.

### Read the ontology editor

![Live ontology editor with entity tree, schema canvas, and summary inspector](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FWRnC5HAgbJZLgLj2P6lM%2Fontology-live-editor.png?alt=media\&token=d9b23baa-2b46-4515-869b-cd51677c7a24)

*The editor makes lifecycle state, schema hierarchy, class configuration, Summary/JSON inspection, version history, logic map, and export available in one workspace.*

The editor is organized into three working areas:

1. **Entity tree** — create or select classes, Item Properties, and relations; search the schema; move between concepts.
2. **Schema canvas** — inspect and edit class properties, options, nested conditions, relation definitions, and ordering.
3. **Inspector** — review class or property identity, description, color, hotkey, geometry, Required state, thumbnails, counts, Summary or JSON, **View logic map**, and export.

The header shows the ontology name, **Version history**, and current lifecycle action or state such as **Publish draft** or **Live**.

### The ontology contract

| Structure       | Meaning in annotation output                                              | Typical example                                                     |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Class           | The concept being labeled.                                                | Person, Vehicle, Defect, Organization.                              |
| Annotation type | How the concept is represented in its native editor.                      | Bounding box, polygon, mask, entity, event, keypoint, line, cuboid. |
| Property        | Typed information about one annotation instance.                          | Severity, material, helmet status.                                  |
| Relation        | A named connection between annotation instances.                          | Person operates Machine; Entity refers to Entity.                   |
| Item Property   | A label for the complete asset, sequence, document, study, or Data Group. | Weather, procedure phase, overall quality.                          |
| Condition       | A rule that reveals a child property only for a relevant parent answer.   | Ask glass color only when container material is Glass.              |
| Validation      | A type-aware constraint and visible invalid state.                        | Numeric range, text length, regex, choice count.                    |

### Lifecycle at a glance

| State or view   | What it means                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------- |
| Draft           | Editable schema work that must be reviewed and tested before production use.                    |
| Live            | The active contract selected for production annotation in its scope.                            |
| Version history | Published versions plus change events, publisher, date, snapshot, and restore-as-draft actions. |
| Snapshot        | Read-only inspection of a published version.                                                    |
| Logic Map       | Read-only visual graph of classes, properties, options, and conditions.                         |

### Choose the next guide

| Goal                                                    | Continue to                                 |
| ------------------------------------------------------- | ------------------------------------------- |
| Create classes and geometry                             | Classes and annotation types.               |
| Add instance detail or whole-item labels                | Properties, relations, and Item Properties. |
| Add Required rules, validation, or conditional branches | Validation and conditional logic.           |
| Inspect Draft, Live, versions, snapshots, or Logic Map  | Draft, Live, and version history.           |
| Confirm operator behavior and project wiring            | Test an ontology in Workbench.              |

{% hint style="warning" %}
Instructions explain how to apply policy; the ontology constrains the structured output. Publish them as one coordinated change whenever meaning, required values, workflow routing, or downstream schema is affected.
{% endhint %}