<!-- # hard line break macro for HTML -->

# fiftyone.core.ontology

Ontology classes for defining reusable annotation and taxonomy structures.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Classes:**

| [`Ontology`](#fiftyone.core.ontology.Ontology)(name[, description])                                 | Abstract base class for ontology types.                           |
|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`AnnotationOntology`](#fiftyone.core.ontology.AnnotationOntology)(name[, description, ...])        | Ontology for defining annotation structures.                      |
| [`Taxonomy`](#fiftyone.core.ontology.Taxonomy)(name, root[, description])                           | Ontology for defining a hierarchical class structure.             |
| [`LabelSchemaOntologyRef`](#fiftyone.core.ontology.LabelSchemaOntologyRef)(dataset_id, field_names) | One dataset's `applied_ontology` references for a given ontology. |

**Functions:**

| [`save_ontology`](#fiftyone.core.ontology.save_ontology)(ontology[, overwrite])            | Saves the given ontology to the database.                                                                     |
|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| [`load_ontology`](#fiftyone.core.ontology.load_ontology)(name)                             | Loads the latest version of an ontology by name.                                                              |
| [`list_ontologies`](#fiftyone.core.ontology.list_ontologies)([glob_patt])                  | Lists ontology names in the database.                                                                         |
| [`ontology_exists`](#fiftyone.core.ontology.ontology_exists)(name)                         | Checks if an ontology with the given name exists.                                                             |
| [`delete_ontology`](#fiftyone.core.ontology.delete_ontology)(name[, force])                | Deletes an ontology and all its versions from the database.                                                   |
| [`apply_ontology`](#fiftyone.core.ontology.apply_ontology)(label_schemas, field_name, ...) | Returns a new `label_schemas` dict with an annotation ontology attached to (or removed from) the given field. |

### *class* fiftyone.core.ontology.Ontology(name: str, description: str | None = None)

Bases: `ABC`

Abstract base class for ontology types.

Ontologies are global, named, versioned resources that define reusable
annotation structures. They are not scoped to any single dataset.
`save()` and `load()` populate [`version`](#fiftyone.core.ontology.Ontology.version),
[`created_at`](#fiftyone.core.ontology.Ontology.created_at), and [`last_modified_at`](#fiftyone.core.ontology.Ontology.last_modified_at).

* **Parameters:**
  * **name** – the ontology name
  * **description** – optional description

**Attributes:**

| [`version`](#fiftyone.core.ontology.Ontology.version)                               | The version of this ontology, or `None` if not yet saved.                 |
|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| [`created_at`](#fiftyone.core.ontology.Ontology.created_at)                         | The datetime this ontology was created, or `None` if not yet saved.       |
| [`last_modified_at`](#fiftyone.core.ontology.Ontology.last_modified_at)             | The datetime this ontology was last modified, or `None` if not yet saved. |
| [`is_annotation_ontology`](#fiftyone.core.ontology.Ontology.is_annotation_ontology) | Whether this ontology is an annotation ontology.                          |
| [`is_taxonomy`](#fiftyone.core.ontology.Ontology.is_taxonomy)                       | Whether this ontology is a taxonomy.                                      |

**Methods:**

| [`save`](#fiftyone.core.ontology.Ontology.save)([overwrite])   | Saves this ontology to the database.     |
|----------------------------------------------------------------|------------------------------------------|
| [`reload`](#fiftyone.core.ontology.Ontology.reload)()          | Reloads this ontology from the database. |
| [`delete`](#fiftyone.core.ontology.Ontology.delete)()          | Deletes this ontology from the database. |
| [`clone`](#fiftyone.core.ontology.Ontology.clone)(new_name)    | Clones this ontology under a new name.   |
| [`to_dict`](#fiftyone.core.ontology.Ontology.to_dict)()        | Serializes this ontology to a dict.      |
| [`from_dict`](#fiftyone.core.ontology.Ontology.from_dict)(d)   | Creates an ontology from a dict.         |

#### *property* version *: int | None*

The version of this ontology, or `None` if not yet saved.

#### *property* created_at *: [datetime](fiftyone.utils.data.md#fiftyone.utils.data.datetime) | None*

The datetime this ontology was created, or `None` if not yet
saved.

#### *property* last_modified_at *: [datetime](fiftyone.utils.data.md#fiftyone.utils.data.datetime) | None*

The datetime this ontology was last modified, or `None` if not
yet saved.

#### *property* is_annotation_ontology *: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)*

Whether this ontology is an annotation ontology.

#### *property* is_taxonomy *: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)*

Whether this ontology is a taxonomy.

#### save(overwrite: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool) = False) → None

Saves this ontology to the database.

* **Parameters:**
  **overwrite** – if True and an ontology with this name already exists
  in the database, adopt its lineage and append a new version.
  Enables JSON/git-driven workflows where an instance built via
  [`from_dict()`](#fiftyone.core.ontology.Ontology.from_dict) is saved without first calling
  [`load_ontology()`](#fiftyone.core.ontology.load_ontology). With the default `False`, saving an
  in-memory instance whose slug collides with a persisted
  ontology is rejected.

#### reload() → None

Reloads this ontology from the database.

#### delete() → None

Deletes this ontology from the database.

#### clone(new_name: str) → [Ontology](#fiftyone.core.ontology.Ontology)

Clones this ontology under a new name.

* **Parameters:**
  **new_name** – the name for the clone
* **Returns:**
  the cloned [`Ontology`](#fiftyone.core.ontology.Ontology)

#### to_dict() → dict

Serializes this ontology to a dict.

* **Returns:**
  a dict

#### *abstractmethod classmethod* from_dict(d: dict) → [Ontology](#fiftyone.core.ontology.Ontology)

Creates an ontology from a dict.

* **Parameters:**
  **d** – an ontology dict
* **Returns:**
  an [`Ontology`](#fiftyone.core.ontology.Ontology)

### *class* fiftyone.core.ontology.AnnotationOntology(name: str, description: str | None = None, taxonomy: [Taxonomy](#fiftyone.core.ontology.Taxonomy) | None = None, attributes: [list](fiftyone.core.session.events.md#fiftyone.core.session.events.Colorscale.list)[[AttributeSpec](fiftyone.core.annotation.attributes.md#fiftyone.core.annotation.attributes.AttributeSpec)] | None = None)

Bases: [`Ontology`](#fiftyone.core.ontology.Ontology)

Ontology for defining annotation structures.

Bundles typed attributes (with optional conditional display logic) and
an optional taxonomy reference into a single document that gets
connected to a label schema on a field.

* **Parameters:**
  * **name** – the ontology name
  * **description** – optional description
  * **taxonomy** – optional [`Taxonomy`](#fiftyone.core.ontology.Taxonomy) instance to bundle with this
    ontology. Stored internally as the taxonomy’s slug.
  * **attributes** – list of `AttributeSpec` instances

Example:

```default
vehicle_classes = Taxonomy(
    name="vehicle_classes",
    root=Node(name="root", values=[Node(name="car")]),
)
AnnotationOntology(
    name="vehicle_damage_ontology",
    description="Vehicle damage annotation",
    taxonomy=vehicle_classes,
    attributes=[
        AttributeSpec(
            name="damage_present",
            type="bool",
            component="checkbox",
        ),
        AttributeSpec(
            name="damage_location",
            type="str",
            component="dropdown",
            values=["front", "rear", "driver_side", "passenger_side"],
            when=WhenEquals(field="damage_present", value=True),
        ),
    ],
)
```

**Methods:**

| [`to_dict`](#fiftyone.core.ontology.AnnotationOntology.to_dict)()      | Serializes this annotation ontology to a dict.                                             |
|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| [`from_dict`](#fiftyone.core.ontology.AnnotationOntology.from_dict)(d) | Creates an [`AnnotationOntology`](#fiftyone.core.ontology.AnnotationOntology) from a dict. |
| [`clone`](#fiftyone.core.ontology.AnnotationOntology.clone)(new_name)  | Clones this ontology under a new name.                                                     |
| [`delete`](#fiftyone.core.ontology.AnnotationOntology.delete)()        | Deletes this ontology from the database.                                                   |
| [`reload`](#fiftyone.core.ontology.AnnotationOntology.reload)()        | Reloads this ontology from the database.                                                   |
| [`save`](#fiftyone.core.ontology.AnnotationOntology.save)([overwrite]) | Saves this ontology to the database.                                                       |

**Attributes:**

| [`created_at`](#fiftyone.core.ontology.AnnotationOntology.created_at)                         | The datetime this ontology was created, or `None` if not yet saved.       |
|-----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| [`is_annotation_ontology`](#fiftyone.core.ontology.AnnotationOntology.is_annotation_ontology) | Whether this ontology is an annotation ontology.                          |
| [`is_taxonomy`](#fiftyone.core.ontology.AnnotationOntology.is_taxonomy)                       | Whether this ontology is a taxonomy.                                      |
| [`last_modified_at`](#fiftyone.core.ontology.AnnotationOntology.last_modified_at)             | The datetime this ontology was last modified, or `None` if not yet saved. |
| [`version`](#fiftyone.core.ontology.AnnotationOntology.version)                               | The version of this ontology, or `None` if not yet saved.                 |

#### to_dict() → dict

Serializes this annotation ontology to a dict.

* **Returns:**
  a dict

#### *classmethod* from_dict(d: dict) → [AnnotationOntology](#fiftyone.core.ontology.AnnotationOntology)

Creates an [`AnnotationOntology`](#fiftyone.core.ontology.AnnotationOntology) from a dict.

* **Parameters:**
  **d** – an annotation ontology dict
* **Returns:**
  an [`AnnotationOntology`](#fiftyone.core.ontology.AnnotationOntology)

#### clone(new_name: str) → [Ontology](#fiftyone.core.ontology.Ontology)

Clones this ontology under a new name.

* **Parameters:**
  **new_name** – the name for the clone
* **Returns:**
  the cloned [`Ontology`](#fiftyone.core.ontology.Ontology)

#### *property* created_at *: [datetime](fiftyone.utils.data.md#fiftyone.utils.data.datetime) | None*

The datetime this ontology was created, or `None` if not yet
saved.

#### delete() → None

Deletes this ontology from the database.

#### *property* is_annotation_ontology *: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)*

Whether this ontology is an annotation ontology.

#### *property* is_taxonomy *: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)*

Whether this ontology is a taxonomy.

#### *property* last_modified_at *: [datetime](fiftyone.utils.data.md#fiftyone.utils.data.datetime) | None*

The datetime this ontology was last modified, or `None` if not
yet saved.

#### reload() → None

Reloads this ontology from the database.

#### save(overwrite: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool) = False) → None

Saves this ontology to the database.

* **Parameters:**
  **overwrite** – if True and an ontology with this name already exists
  in the database, adopt its lineage and append a new version.
  Enables JSON/git-driven workflows where an instance built via
  [`from_dict()`](#fiftyone.core.ontology.AnnotationOntology.from_dict) is saved without first calling
  [`load_ontology()`](#fiftyone.core.ontology.load_ontology). With the default `False`, saving an
  in-memory instance whose slug collides with a persisted
  ontology is rejected.

#### *property* version *: int | None*

The version of this ontology, or `None` if not yet saved.

### *class* fiftyone.core.ontology.Taxonomy(name: str, root: [Node](fiftyone.core.annotation.nodes.md#fiftyone.core.annotation.nodes.Node), description: str | None = None)

Bases: [`Ontology`](#fiftyone.core.ontology.Ontology)

Ontology for defining a hierarchical class structure.

A taxonomy is a named, versioned, self-contained class hierarchy.
Label schema fields reference a taxonomy by `name` instead of
inlining a flat class list, so the same hierarchy can be shared
across multiple datasets.

* **Parameters:**
  * **name** – the taxonomy name
  * **description** – optional description
  * **root** – the root `Node` of the hierarchy. Required.

Example:

```default
Taxonomy(
    name="vehicle_classes",
    root=Node(
        name="vehicles",
        can_select=False,
        values=[
            Node(name="car"),
            Node(name="truck"),
            Node(name="motorcycle"),
        ],
    ),
)
```

**Methods:**

| [`to_dict`](#fiftyone.core.ontology.Taxonomy.to_dict)()      | Serializes this taxonomy to a dict.                                   |
|--------------------------------------------------------------|-----------------------------------------------------------------------|
| [`from_dict`](#fiftyone.core.ontology.Taxonomy.from_dict)(d) | Creates a [`Taxonomy`](#fiftyone.core.ontology.Taxonomy) from a dict. |
| [`clone`](#fiftyone.core.ontology.Taxonomy.clone)(new_name)  | Clones this ontology under a new name.                                |
| [`delete`](#fiftyone.core.ontology.Taxonomy.delete)()        | Deletes this ontology from the database.                              |
| [`reload`](#fiftyone.core.ontology.Taxonomy.reload)()        | Reloads this ontology from the database.                              |
| [`save`](#fiftyone.core.ontology.Taxonomy.save)([overwrite]) | Saves this ontology to the database.                                  |

**Attributes:**

| [`created_at`](#fiftyone.core.ontology.Taxonomy.created_at)                         | The datetime this ontology was created, or `None` if not yet saved.       |
|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| [`is_annotation_ontology`](#fiftyone.core.ontology.Taxonomy.is_annotation_ontology) | Whether this ontology is an annotation ontology.                          |
| [`is_taxonomy`](#fiftyone.core.ontology.Taxonomy.is_taxonomy)                       | Whether this ontology is a taxonomy.                                      |
| [`last_modified_at`](#fiftyone.core.ontology.Taxonomy.last_modified_at)             | The datetime this ontology was last modified, or `None` if not yet saved. |
| [`version`](#fiftyone.core.ontology.Taxonomy.version)                               | The version of this ontology, or `None` if not yet saved.                 |

#### to_dict() → dict

Serializes this taxonomy to a dict.

* **Returns:**
  a dict

#### *classmethod* from_dict(d: dict) → [Taxonomy](#fiftyone.core.ontology.Taxonomy)

Creates a [`Taxonomy`](#fiftyone.core.ontology.Taxonomy) from a dict.

* **Parameters:**
  **d** – a taxonomy dict
* **Returns:**
  a [`Taxonomy`](#fiftyone.core.ontology.Taxonomy)

#### clone(new_name: str) → [Ontology](#fiftyone.core.ontology.Ontology)

Clones this ontology under a new name.

* **Parameters:**
  **new_name** – the name for the clone
* **Returns:**
  the cloned [`Ontology`](#fiftyone.core.ontology.Ontology)

#### *property* created_at *: [datetime](fiftyone.utils.data.md#fiftyone.utils.data.datetime) | None*

The datetime this ontology was created, or `None` if not yet
saved.

#### delete() → None

Deletes this ontology from the database.

#### *property* is_annotation_ontology *: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)*

Whether this ontology is an annotation ontology.

#### *property* is_taxonomy *: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)*

Whether this ontology is a taxonomy.

#### *property* last_modified_at *: [datetime](fiftyone.utils.data.md#fiftyone.utils.data.datetime) | None*

The datetime this ontology was last modified, or `None` if not
yet saved.

#### reload() → None

Reloads this ontology from the database.

#### save(overwrite: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool) = False) → None

Saves this ontology to the database.

* **Parameters:**
  **overwrite** – if True and an ontology with this name already exists
  in the database, adopt its lineage and append a new version.
  Enables JSON/git-driven workflows where an instance built via
  [`from_dict()`](#fiftyone.core.ontology.Taxonomy.from_dict) is saved without first calling
  [`load_ontology()`](#fiftyone.core.ontology.load_ontology). With the default `False`, saving an
  in-memory instance whose slug collides with a persisted
  ontology is rejected.

#### *property* version *: int | None*

The version of this ontology, or `None` if not yet saved.

### fiftyone.core.ontology.save_ontology(ontology: [Ontology](#fiftyone.core.ontology.Ontology), overwrite: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool) = False) → None

Saves the given ontology to the database.

Module-level mirror of [`Ontology.save()`](#fiftyone.core.ontology.Ontology.save), paired with
[`load_ontology()`](#fiftyone.core.ontology.load_ontology) and [`delete_ontology()`](#fiftyone.core.ontology.delete_ontology).

* **Parameters:**
  * **ontology** – an [`Ontology`](#fiftyone.core.ontology.Ontology) to save
  * **overwrite** – see [`Ontology.save()`](#fiftyone.core.ontology.Ontology.save)

### fiftyone.core.ontology.load_ontology(name: str) → [Ontology](#fiftyone.core.ontology.Ontology)

Loads the latest version of an ontology by name.

* **Parameters:**
  **name** – the ontology name
* **Returns:**
  an [`Ontology`](#fiftyone.core.ontology.Ontology)
* **Raises:**
  **ValueError** – if no ontology with the given name exists

### fiftyone.core.ontology.list_ontologies(glob_patt: str | None = None) → [list](fiftyone.core.session.events.md#fiftyone.core.session.events.Colorscale.list)[str]

Lists ontology names in the database.

* **Parameters:**
  **glob_patt** – an optional glob pattern to filter names
* **Returns:**
  a sorted list of ontology names

### fiftyone.core.ontology.ontology_exists(name: str) → [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool)

Checks if an ontology with the given name exists.

* **Parameters:**
  **name** – the ontology name
* **Returns:**
  True/False

### *class* fiftyone.core.ontology.LabelSchemaOntologyRef(dataset_id: str, field_names: [list](fiftyone.core.session.events.md#fiftyone.core.session.events.Colorscale.list)[str])

Bases: `NamedTuple`

One dataset’s `applied_ontology` references for a given ontology.

#### dataset_id

the `DatasetDocument` id (string form)

* **Type:**
  str

#### field_names

the label-schema field names on that dataset that
reference the ontology

* **Type:**
  [list](fiftyone.core.session.events.md#fiftyone.core.session.events.Colorscale.list)[str]

**Attributes:**

| [`dataset_id`](#id0)   | Alias for field number 0   |
|------------------------|----------------------------|
| [`field_names`](#id1)  | Alias for field number 1   |

**Methods:**

| [`count`](#fiftyone.core.ontology.LabelSchemaOntologyRef.count)(value, /)             | Return number of occurrences of value.   |
|---------------------------------------------------------------------------------------|------------------------------------------|
| [`index`](#fiftyone.core.ontology.LabelSchemaOntologyRef.index)(value[, start, stop]) | Return first index of value.             |

#### dataset_id *: str*

Alias for field number 0

#### field_names *: [list](fiftyone.core.session.events.md#fiftyone.core.session.events.Colorscale.list)[str]*

Alias for field number 1

#### count(value,)

Return number of occurrences of value.

#### index(value, start=0, stop=9223372036854775807,)

Return first index of value.

Raises ValueError if the value is not present.

### fiftyone.core.ontology.delete_ontology(name: str, force: [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool) = False) → None

Deletes an ontology and all its versions from the database.

If any label schema references this ontology (via
`applied_ontology` on a field), the default behavior is to raise
rather than silently break those schemas. Pass `force=True` to
inline the ontology’s attributes into each affected schema as
permanent local copies and then delete the ontology.

Inlining and deletion run as two phases: every affected schema is
inlined and saved first, and the ontology is deleted only if every
save succeeds. If something fails mid-inline, the ontology still
exists and the call is safely re-runnable — already-inlined
schemas no longer match the lookup.

* **Parameters:**
  * **name** – the ontology name
  * **force** – if False (default), raise if any label schema references
    the ontology. If True, inline the ontology’s attributes
    into each affected schema as local copies before deleting.
* **Raises:**
  **ValueError** – if the ontology does not exist, or if it is in use
      and `force=False`

### fiftyone.core.ontology.apply_ontology(label_schemas: dict, field_name: str, ontology_name: str | None) → dict

Returns a new `label_schemas` dict with an annotation ontology
attached to (or removed from) the given field.

Pure function — does not mutate the input. Apply the result via
[`fiftyone.core.dataset.Dataset.set_label_schemas()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.set_label_schemas) to persist.

* **Parameters:**
  * **label_schemas** – a label schemas dict
  * **field_name** – the field to attach the ontology to
  * **ontology_name** – name of an annotation ontology to attach, or `None`
    to unset an existing reference
* **Returns:**
  a new label schemas dict