Ontologies

Access ontologies through client.ontologies in the Datature Vi SDK.

An ontology defines the set of labels, tags, or classes that annotations in a dataset may reference. Ontologies are versioned: creating a new version preserves the historical record, so existing annotations stay linked to the version they were created against while new annotations target the updated taxonomy.

Methods

list()

List ontologies attached to a dataset.

ontologies = client.ontologies.list("dataset_abc123")

for ontology in ontologies.items:
    print(ontology["ontologyId"])

for ontology in client.ontologies(dataset_id="dataset_abc123"):
    print(ontology["ontologyId"])

for ontology in client.ontologies.list("dataset_abc123").all_items():
    labels = ontology.get("spec", {}).get("labels", [])
    print(f"{ontology['ontologyId']}: {[l['name'] for l in labels]}")

Returns: PaginatedResponse[dict]. A page of ontology documents.

get()

Fetch a single ontology by ID, including its current version.

ontology = client.ontologies.get("dataset_abc123", "ontology_xyz")

print(ontology["spec"]["labels"])

Returns: dict. The ontology document, including its current version.

update()

Patch select fields of an ontology in place. Only the fields you provide are modified.

client.ontologies.update(
    "dataset_abc123",
    "ontology_xyz",
    {"metadata": {"attributes": {"note": "reviewed"}}},
)

Returns: dict. The updated ontology document.

replace()

Fully replace an ontology document. Use this when migrating a label set wholesale; use update() for incremental edits.

client.ontologies.replace(
    "dataset_abc123",
    "ontology_xyz",
    {"spec": {"labels": [{"name": "car"}]}},
)

Returns: dict. The updated ontology document.

create_version()

Create a new version of an ontology.

Versioning preserves history: existing annotations remain linked to the version they were created against, while new annotations target the latest version.

new_version = client.ontologies.create_version(
    dataset_id="dataset_abc123",
    ontology_id="ontology_xyz",
    body={"spec": {"labels": [{"name": "car"}, {"name": "truck"}]}},
)

print(new_version["spec"]["version"])

current = client.ontologies.get("dataset_abc123", "ontology_xyz")
labels = current["spec"]["labels"] + [{"name": "motorcycle"}]

client.ontologies.create_version(
    dataset_id="dataset_abc123",
    ontology_id="ontology_xyz",
    body={"spec": {"labels": labels}},
)

Returns: dict. The ontology document at the newly created version.

Response format

Ontologies are returned as plain dictionaries mirroring the platform's ontology documents.

Related resources