Ontology management

A clean, thoughtful ontology is critical for creating high-quality labeled data with minimal errors and inconsistencies.

Every ontology is made up of schema nodes and feature schemas. The schema nodes provide the "tree" structure. Each schema node contains information regarding the parents, children, and the structure of this specific ontology. The feature schemas are the reusable "leaves" of the tree structure. Each feature schema contains all of the information for rendering a feature of its kind, such as class name, and color, and type.

The diagram below illustrates how a simple ontology would be structured.

When creating a new project, you can configure the ontology in one of three ways:

Create a new ontology. Useful if you are just starting out with Labelbox or if you just need to create a new ontology completely from scratch.
Use a shared ontology. Do this if you have multiple projects that need to reference the ontology.
Create a copy of an existing ontology. Create a copy of an existing ontology to use as a starting point rather than creating one completely from scratch.

Create a new ontology

When you create a new project, a new ontology is automatically created is named after the project. By default, that ontology will only be connected to that one project.

When exploring the ontologies in the dropdown menu, you can click the “x” icon to go back to the ontology that was automatically created for that project.

Objects

Objects are annotations on the pixels of an image/video frame or on the characters in a text string.

The following annotation types are categorized as Objects:

Bounding box
Polygon
Point
Polyline
Mask
Entity

Classifications

A Classification is a semantic annotation on an asset and does not include any geometric annotation or per-pixel classification information. Classifications can be on the asset itself (AKA global) or nested within Object annotations.

The following annotation types are categorized as Classifications:

Radio
Checklist
Dropdown
Free-form

For Radio classifications, you have the option to make the answer searchable in the Editor. This feature is particularly helpful if your Radio classification has many answer choices.

Connect to a shared ontology

Connecting your project to an existing ontology is helpful if you want multiple projects to reference the same ontology.

Use the dropdown at the top to select an ontology. You can either use the shared ontology as is, or you can bypass the modal window to make edits to the referenced ontology.

Warning

Any change to a shared ontology will impact all projects referencing this ontology. This is not reversible.

Copy an existing ontology

To copy an existing ontology, select an ontology from the dropdown menu, then click the three dots icon in the corner and select Create copy. All changes made to the copied ontology will only affect the project your configuring. Copied ontologies can, later on, be shared.

Rename the ontology

At any point, you can use the context menu's Rename option to rename your ontology. Note that renaming a shared ontology will rename the ontology for all projects referencing that ontology. A strategic naming convention for your ontologies can make them easier to find in the dropdown list.

Sample ontology

To query the ontology from one of your projects, use this GraphQL query:

query {
     project (where: {id: "<PROJECT_ID>"}) {
         ontology {
             normalized
         }
     }
}

Below is a sample ontology containing a Bounding box object and a Radio classification.

{ 
    "tools": [ 
        { 
            "schemaNodeId": "ck5cxrgenqzi00899gfrggvr4", 
            "featureSchemaId": "ck5cxrgdxjepy0952ttth9a96", 
            "required": false, 
            "name": "Dog", 
            "color": "#FF0000", 
            "tool": "rectangle", 
            "classifications": [] 
        } 
    ], 
    "classifications": [ 
        { 
            "schemaNodeId": "ck62vcr24s79h08337bijdab3", 
            "featureSchemaId": "ck62vcr1es78x0833r1uxg6jz", 
            "required": true, 
            "instructions": "This is a question.", 
            "name": "this_is_a_question.", 
            "type": "radio", 
            "options": [ 
                { 
                    "schemaNodeId": "ck62vcr0d0be30876ojpf3qwf", 
                    "featureSchemaId": "ck62vcqzo0go60700u048bzqv", 
                    "label": "Yes", 
                    "value": "yes" 
                }, 
                { 
                    "schemaNodeId": "ck62vcr0d0be40876uya7zei2", 
                    "featureSchemaId": "ck62vcqzo0go70700v16eg61d", 
                    "label": "No", 
                    "value": "no" 
                } 
            ]
        } 
    ]
}

Where:

tools is the top-level JSON key designated for vector and mask annotations (AKA Objects).
classifications represents global classifications when at the root-level. classifications nested within tools represents a classification nested within a vector or mask annotation.
schemaNodeId represents the annotation schema node containing all of the information regarding the structure (ie parent-child relationships).
featureSchemaId represents the annotation schema containing all of the necessary information for rendering an annotation of its kind such as name, color, and type.
name refers to the name of the object or classification annotation.
color refers to the color of the mask or vector feature on the asset.
tool represents the labeling tool used to create the annotation (e.g. Bounding box, polygon, polyline, point, mask, or entity).
instructions is the text that appears as the classification question to the labeler.
type refers to the classification type (radio, checklist, text, or dropdown).
options are the possible classification answers.
label refers to the text that appears to the labeler as a possible answer to the classification question.
value refers to the classification answer.
required indicates whether the object requires use or the classification question requires an answer.

In this section:

Labelbox documentation