fiftyone.core.ontology#

Ontology classes for defining reusable annotation and taxonomy structures.

Copyright 2017-2026, Voxel51, Inc.
voxel51.com

Classes:

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

Functions:

`save_ontology`(ontology[, overwrite])	Saves the given ontology to the database.
`load_ontology`(name)	Loads the latest version of an ontology by name.
`list_ontologies`([glob_patt])	Lists ontology names in the database.
`ontology_exists`(name)	Checks if an ontology with the given name exists.
`delete_ontology`(name[, force])	Deletes an ontology and all its versions from the database.
`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, created_at, and last_modified_at.

Parameters:

name – the ontology name
description – optional description

Attributes:

`version`	The version of this ontology, or `None` if not yet saved.
`created_at`	The datetime this ontology was created, or `None` if not yet saved.
`last_modified_at`	The datetime this ontology was last modified, or `None` if not yet saved.
`is_annotation_ontology`	Whether this ontology is an annotation ontology.
`is_taxonomy`	Whether this ontology is a taxonomy.

Methods:

`save`([overwrite])	Saves this ontology to the database.
`reload`()	Reloads this ontology from the database.
`delete`()	Deletes this ontology from the database.
`clone`(new_name)	Clones this ontology under a new name.
`to_dict`()	Serializes this ontology to a dict.
`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 | None#: The datetime this ontology was created, or None if not yet saved.

property last_modified_at: datetime | None#: The datetime this ontology was last modified, or None if not yet saved.

property is_annotation_ontology: bool#: Whether this ontology is an annotation ontology.

property is_taxonomy: bool#: Whether this ontology is a taxonomy.

save(overwrite: 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() is saved without first calling 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#

Clones this ontology under a new name.

Parameters:: new_name – the name for the clone
Returns:: the cloned Ontology

to_dict() → dict#

Serializes this ontology to a dict.

Returns:: a dict

abstractmethod classmethod from_dict(d: dict) → Ontology#

Creates an ontology from a dict.

Parameters:: d – an ontology dict
Returns:: an Ontology

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

Bases: 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 instance to bundle with this ontology. Stored internally as the taxonomy’s slug.
attributes – list of AttributeSpec instances

Example:

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`()	Serializes this annotation ontology to a dict.
`from_dict`(d)	Creates an `AnnotationOntology` from a dict.
`clone`(new_name)	Clones this ontology under a new name.
`delete`()	Deletes this ontology from the database.
`reload`()	Reloads this ontology from the database.
`save`([overwrite])	Saves this ontology to the database.

Attributes:

`created_at`	The datetime this ontology was created, or `None` if not yet saved.
`is_annotation_ontology`	Whether this ontology is an annotation ontology.
`is_taxonomy`	Whether this ontology is a taxonomy.
`last_modified_at`	The datetime this ontology was last modified, or `None` if not yet saved.
`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#

Creates an AnnotationOntology from a dict.

Parameters:: d – an annotation ontology dict
Returns:: an AnnotationOntology

clone(new_name: str) → Ontology#

Clones this ontology under a new name.

Parameters:: new_name – the name for the clone
Returns:: the cloned Ontology

property created_at: 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#: Whether this ontology is an annotation ontology.

property is_taxonomy: bool#: Whether this ontology is a taxonomy.

property last_modified_at: 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 = 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() is saved without first calling 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, description: str | None = None)#

Bases: 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:

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

Methods:

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

Attributes:

`created_at`	The datetime this ontology was created, or `None` if not yet saved.
`is_annotation_ontology`	Whether this ontology is an annotation ontology.
`is_taxonomy`	Whether this ontology is a taxonomy.
`last_modified_at`	The datetime this ontology was last modified, or `None` if not yet saved.
`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#

Creates a Taxonomy from a dict.

Parameters:: d – a taxonomy dict
Returns:: a Taxonomy

clone(new_name: str) → Ontology#

Clones this ontology under a new name.

Parameters:: new_name – the name for the clone
Returns:: the cloned Ontology

property created_at: 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#: Whether this ontology is an annotation ontology.

property is_taxonomy: bool#: Whether this ontology is a taxonomy.

property last_modified_at: 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 = 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() is saved without first calling 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, overwrite: bool = False) → None#

Saves the given ontology to the database.

Module-level mirror of Ontology.save(), paired with load_ontology() and delete_ontology().

Parameters:

ontology – an Ontology to save
overwrite – see Ontology.save()

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

Loads the latest version of an ontology by name.

Parameters:: name – the ontology name
Returns:: an Ontology
Raises:: ValueError – if no ontology with the given name exists

fiftyone.core.ontology.list_ontologies(glob_patt: str | None = None) → 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#

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[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[str]

Attributes:

`dataset_id`	Alias for field number 0
`field_names`	Alias for field number 1

Methods:

`count`(value, /)	Return number of occurrences of value.
`index`(value[, start, stop])	Return first index of value.

dataset_id: str#: Alias for field number 0

field_names: 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 = 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() 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