---
question: Does Ontology Import replace a module Turtle file?
kind: task
via_web: available
via_cli: na
via_python: available
via_api: available
via_config: na
ref_web: Ontology › Import
ref_python: triple_store.load_schema
ref_api: POST /api/ontology/import
next:
  - /capabilities/build/knowledge-graph/enable-ontology
  - /capabilities/build/knowledge-graph/generate-python-classes
---

# Import an ontology

There are two kinds of import. They do different things:

- **A reference ontology in Nexus** (Web UI, REST API). Nexus reads the file and lists its classes and properties under References in the Ontology sidebar. The browser keeps it. The engine does not load it into the triple store, and it does not appear in Settings › Ontologies.
- **A module ontology** (Python). The file goes into a module's `ontologies/` folder. The engine loads it into the schema graph `http://ontology.naas.ai/graph/schema` at startup, and workspaces can [enable it](/user-guide/build/knowledge-graph/enable-ontology).

Use the first to browse a vocabulary next to your own. Use the second when agents, pipelines and queries should use it.

## Web UI

### Open the import screen

In the workspace, open Ontology. In its File menu, choose **Import Ontology…**. The screen reads "Upload a Turtle, OWL or RDF file to register it as a reference ontology."

### Choose the file

Drop the file on "Drop your ontology file here", or click to browse. The picker accepts `.ttl`, `.owl`, `.rdf`, `.n3` and `.nt`, but only Turtle text is read: see the warning below.

![Ontology import screen](/abi/Screenshot_Ontology_Import.png)

*Ontology › Import: drop a Turtle, OWL or RDF file, or click to browse.*

### Import it

Click **Import**. A notice gives the number of classes and properties read, and the file joins the Import History table. **Done** opens the ontology network.

:::warning What the import reads
The import matches Turtle text with two patterns, and nothing else:

- a class written with a full IRI and more statements after it: `<http://…/Item> a owl:Class ; …`
- an object property written `<http://…/hasItem> rdf:type owl:ObjectProperty`, with `rdf:type`, not `a`.

Prefixed names (`my:Item a owl:Class`), datatype properties, and RDF/XML or N-Triples files (`.owl`, `.rdf`, `.nt`) import with 0 classes and 0 properties. To load such a file for real, add it to a module (Python tab). Reference ontologies and the import history are kept in this browser's storage, not on the server.
:::

## CLI

Not applicable. There is no `abi` command that imports an ontology. To load a file into the engine, put it under a module's `ontologies/` folder (Python tab). To browse it in a workspace, use the Web UI. The command list is the [CLI reference](/user-guide/reference/cli).

## Python

### Add the file to a module

Copy the Turtle file into an in-engine module, for example `src/my_module/ontologies/modules/ExternalOntology.ttl`. The engine loads every `*.ttl` under `ontologies/`, recursively, the next time it starts. The file must parse as Turtle: other formats need converting first, for example with `rdflib`:

```python title="scripts/convert_to_turtle.py"
from rdflib import Graph

Graph().parse("external.owl").serialize(
    "src/my_module/ontologies/modules/ExternalOntology.ttl", format="turtle"
)
```

### Load it without a restart

```python title="scripts/load_ontology.py"
from pathlib import Path

from my_module import ABIModule

ttl = Path("src/my_module/ontologies/modules/ExternalOntology.ttl").resolve()
triple_store = ABIModule.get_instance().engine.services.triple_store
triple_store.load_schema(str(ttl))
```

Run it with `abi run script scripts/load_ontology.py`, which loads the engine first. The module must list `TripleStoreService` in its `dependencies`. Pass the absolute path: the engine records each file by the path it loaded it from. `remove_schema(path)` takes a file back out.

### Restart, then enable it in a workspace

`load_schema` puts the triples in the schema graph, but the workspace catalog does not see the file yet. Nexus builds the catalog from each module's list of ontology files, read once when the module loads. Until the engine restarts, Settings › Ontologies does not list the file, and saving its id through the REST API returns 422.

After a restart, a file that declares `a owl:Ontology` is in the catalog. Turn it on in [Enable in a workspace](/user-guide/build/knowledge-graph/enable-ontology).

## REST API

### Send the file

```bash
jq -n --rawfile content external.ttl '{content: $content, filename: "external.ttl"}' |
  curl -s -X POST "http://localhost:9879/api/ontology/import" \
    -H "Authorization: Bearer $NEXUS_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @-
```

`jq` builds the JSON body and pipes it to `curl`, so a large file does not hit the shell's limit on argument size.

`content` is the file text (up to 5,000,000 characters). `filename` is a plain file name with an extension. The token is a Nexus login token: see [Enable in a workspace](/user-guide/build/knowledge-graph/enable-ontology?via=api) for the sign-in call.

### Read the result

The response is the parsed reference ontology: `id`, `name`, `file_path`, `format`, `imported_at`, and its `classes` and `properties` with their IRIs, labels and definitions. The server keeps nothing: the Web UI stores this response in the browser. The same reading rules apply as in the Web UI warning.

## Config

Not applicable. No `config.yaml` key loads a Turtle file from outside a module. A file is loaded because it sits under the `ontologies/` folder of a module listed under `modules:`. A workspace's `ontologies:` list only picks from those files: see [Enable in a workspace](/user-guide/build/knowledge-graph/enable-ontology?via=config).