---
updatedAt: 2026-08-25T18:33:56.000Z
agentTools:
  projectIndex: https://vi.developers.datature.com/llms.txt
---

# 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.

<ViCallout type="info" title="Before You Start">
  * [Vi SDK installed](https://vi.developers.datature.com/docs/vi-sdk-installation) with authentication configured
  * An existing [dataset](https://vi.developers.datature.com/docs/vi-sdk-datasets)
  * Familiarity with [annotation guidelines](https://vi.developers.datature.com/docs/annotation-guide)

  **[Get started with the Vi SDK →](https://vi.developers.datature.com/docs/vi-sdk-getting-started)**
</ViCallout>

<ViCallout type="warning" title="Knowledge-Base Datasets">
  Knowledge-base style datasets do not support ontology mutation. The server returns a 403 if you call `update()`, `replace()`, or `create_version()` against one.
</ViCallout>

***

## Methods

### list()

List ontologies attached to a dataset.

<CodeGroup>
```python Basic listing
ontologies = client.ontologies.list("dataset_abc123")

for ontology in ontologies.items:
    print(ontology["ontologyId"])
```
</CodeGroup>

<CodeGroup>
```python Iterate with the call syntax
for ontology in client.ontologies(dataset_id="dataset_abc123"):
    print(ontology["ontologyId"])
```
</CodeGroup>

<CodeGroup>
```python Inspect every label across ontologies
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]}")
```
</CodeGroup>

<ParamTable title="Parameters">
  <Param name="dataset_id" type="string" required={true} description="Owning dataset." />
  <Param name="filter_criteria" type="string" required={false} description="Optional filter expression." defaultValue="None" />
  <Param name="page_size" type="integer" required={false} description="Page size cap." defaultValue="None" />
  <Param name="page" type="string" required={false} description="Pagination cursor from a previous call." defaultValue="None" />
</ParamTable>

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

***

### get()

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

<CodeGroup>
```python Basic usage
ontology = client.ontologies.get("dataset_abc123", "ontology_xyz")

print(ontology["spec"]["labels"])
```
</CodeGroup>

<ParamTable title="Parameters">
  <Param name="dataset_id" type="string" required={true} description="Owning dataset." />
  <Param name="ontology_id" type="string" required={true} description="Ontology identifier." />
</ParamTable>

**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.

<CodeGroup>
```python Update metadata
client.ontologies.update(
    "dataset_abc123",
    "ontology_xyz",
    {"metadata": {"attributes": {"note": "reviewed"}}},
)
```
</CodeGroup>

<ParamTable title="Parameters">
  <Param name="dataset_id" type="string" required={true} description="Owning dataset." />
  <Param name="ontology_id" type="string" required={true} description="Ontology identifier." />
  <Param name="body" type="object" required={true} description="Partial document containing only the fields to update." />
</ParamTable>

**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.

<CodeGroup>
```python Replace the label set
client.ontologies.replace(
    "dataset_abc123",
    "ontology_xyz",
    {"spec": {"labels": [{"name": "car"}]}},
)
```
</CodeGroup>

<ParamTable title="Parameters">
  <Param name="dataset_id" type="string" required={true} description="Owning dataset." />
  <Param name="ontology_id" type="string" required={true} description="Ontology identifier." />
  <Param name="body" type="object" required={true} description="Full ontology document: spec, metadata, and so on." />
</ParamTable>

**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.

<CodeGroup>
```python Add classes in a new 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"])
```
</CodeGroup>

<CodeGroup>
```python Extend the existing label set
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}},
)
```
</CodeGroup>

<ParamTable title="Parameters">
  <Param name="dataset_id" type="string" required={true} description="Owning dataset." />
  <Param name="ontology_id" type="string" required={true} description="Ontology identifier." />
  <Param name="body" type="object" required={true} description="Version-create payload, typically a spec with the updated label set." />
</ParamTable>

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

***

## Response format

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

<ParamTable title="Common fields">
  <Param name="ontologyId" type="string" description="Unique ontology identifier" />
  <Param name="spec" type="object" description="Ontology specification: the label set and version" />
  <Param name="spec.labels" type="array" description="Label definitions available to annotations" />
  <Param name="spec.version" type="string" description="Current version identifier" />
  <Param name="metadata" type="object" description="Creation and update timestamps" />
</ParamTable>

***

## Related resources

<BentoGrid className="grid grid-cols-1 md:grid-cols-2 gap-6 my-10">
  <BentoCard title="Annotations API" description="Upload, list, get, download, and delete annotations." href="http://vi.developers.datature.com/docs/vi-sdk-annotations" faIcon="fa-solid fa-tags" />
  <BentoCard title="Datasets API" description="List, get, export, download, and delete datasets." href="http://vi.developers.datature.com/docs/vi-sdk-datasets" faIcon="fa-solid fa-database" />
  <BentoCard title="Annotation Guide" description="How to write consistent annotations and label taxonomies." href="http://vi.developers.datature.com/docs/annotation-guide" faIcon="fa-solid fa-book" />
  <BentoCard title="Annotation Import Sessions API" description="Inspect and manage bulk annotation imports." href="http://vi.developers.datature.com/docs/vi-sdk-annotation-import-sessions" faIcon="fa-solid fa-file-import" />
</BentoGrid>