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.
`LabelSchemaOntologyRef`(dataset_id, field_names)	One dataset's `applied_ontology` references for a given ontology.

Functions:

`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`()	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() → None#: Saves this ontology to the database.

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, taxonomies: list[str] | None = None, attributes: list[AttributeSpec] | None = None)#

Bases: Ontology

Ontology for defining annotation structures.

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

Parameters:

name – the ontology name
description – optional description
taxonomies – list of taxonomy names referenced by this ontology
attributes – list of AttributeSpec instances

Example:

AnnotationOntology(
    name="vehicle_damage_ontology",
    description="Vehicle damage annotation",
    taxonomies=["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`()	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() → None#: Saves this ontology to the database.

property version: int | None#: The version of this ontology, or None if not yet saved.

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