Ontology API reference

NAMS-backend only. All methods raise NotSupportedError on bolt.

Methods

Python TypeScript Semantics

ontology.list()

ontology.list()

System templates + workspace-owned ontologies; the active one is flagged (is_active).

ontology.get(id)

ontology.get(id)

One ontology with its full revision history ({record, versions[]}).

ontology.get_active()

ontology.getActive()

Active version’s parsed document + composed validation_mode / revision / version_id.

ontology.clone(template_name)

ontology.clone(templateName)

Editable workspace copy of a system template; returns the rev-1 version.

ontology.create(name, schema, validation_mode=None)

ontology.create({name, schema, validationMode?})

New workspace ontology from a schema document; returns the rev-1 version.

ontology.update(id, schema, validation_mode=None)

ontology.update({id, schema, validationMode?})

New immutable revision (n+1); returns it.

ontology.activate(version_id)

ontology.activate(versionId)

Bind a version; subsequent entity writes validate against it.

ontology.delete(id)

ontology.delete(id)

Delete a workspace-owned ontology.

ontology.import_(content=/url=, format=)

ontology.import({content?, url?, format?})

Convert an external graph/ontology document into a non-persisted draft (OntologyImportResult). Nothing is saved until you create() / update() from the returned document. Note the trailing underscore on the Python name (import is a keyword).

ontology.diff(id, from_revision, to_revision)

ontology.diff(id, fromRevision, toRevision)

Structural diff between two revisions of an ontology (OntologyDiff).

ontology.migrate(id, from_version_id=, to_version_id=, type_mappings=, dry_run=False)

ontology.migrate(id, {fromVersionId, toVersionId, typeMappings, dryRun?})

Enqueue an async label-rename migration from one version to another; returns a MigrationJob. Pass dry_run=True to preview without writing.

ontology.get_migration(job_id)

ontology.getMigration(jobId)

Poll a migration job’s status and progress (MigrationJob).

Return types

list() returns OntologySummary[]. get() returns Ontology ({record, versions[]}). get_active() returns ActiveOntology. clone / create / update / activate return an OntologyVersion.

import_() returns an OntologyImportResult ({document?, warnings[] (ImportWarning), detected_format?, suggested_name?}). diff() returns an OntologyDiff ({from_revision, to_revision, entity_types, relationships, mode_change?}). migrate() and get_migration() return a MigrationJob ({id, status (pending|running|completed|failed|paused), total, processed, errored, …}).

Import formats

import_() accepts these format ids (or auto / omit to detect from content):

format Source

arrows

Arrows.app JSON

data-importer

Neo4j Data Importer model

cypher

Cypher DDL (CREATE CONSTRAINT / schema statements)

graphql

GraphQL SDL type definitions

linkml

LinkML schema

rdf

RDF / OWL (parsed server-side; the extraction service must be reachable)

native

The library’s own ontology JSON/YAML (yaml / yml alias to native)

auto

Detect from content (the default when format is omitted)

Ontology document schema

Field Shape Notes

domain

{id, name, description?, tagline?, emoji?}

Identity + display metadata.

entity_types[]

{label, pole_type, subtype?, color?, icon?, properties[]}

pole_type ∈ PERSON / ORGANIZATION / LOCATION / EVENT / OBJECT.

…properties[]

{name, type, required?, unique?, enum?}

type ∈ string / datetime / date / float / integer.

relationships[]

{type, source, target}

type is UPPER_SNAKE; source/target are entity labels.

The OntologyVersion carries id, ontology_id, revision, validation_mode (permissive | strict), the parsed document, schema_hash, created_at, and message.

REST endpoints

The SDK targets these workspace-scoped endpoints (under the versioned base, e.g. /v1). Request bodies use snake_case. See the OpenAPI spec for exact request/response shapes.

Method Path Maps to

GET

/ontologies

list()

GET

/ontologies/{id}

get()

GET

/ontologies/active

get_active()

POST

/ontologies/{name}/clone

clone()

POST

/ontologies — body {ontology, validation_mode?}

create()

PUT

/ontologies/{id} — body {ontology, validation_mode?}

update()

POST

/ontologies/active — body {version_id}

activate()

DELETE

/ontologies/{id}

delete()

POST

/ontologies/import — body {content?, url?, format?}

import_() / import()

GET

/ontologies/{id}/diff?from={n}&to={m}

diff()

POST

/ontologies/{id}/migrate

migrate()

GET

/ontologies/migrations/{job_id}

get_migration()

migrate runs asynchronously: POST /ontologies/{id}/migrate returns a MigrationJob you poll with get_migration() (the service also exposes /migrations/{job_id}/pause and /resume). The preview/dry-run path of import is rate-limited to 30 requests/hour/workspace (see NAMS Limits & Behavior).

Errors

Condition Exception

Strict-mode validation rejection

ValidationError (carries the offending detail)

Ontology method on the bolt backend

NotSupportedError (workaround: SchemaModel.CUSTOM)

No active ontology bound

NotSupportedError

System templates

~28 system templates ship on the service (each is_system = true, revision 1). nams-default is bound until a workspace activates its own:

agent-memory, conservation, cybersecurity, data-journalism, digital-twin, education, financial-services, gaming, genai-llm-ops, gis-cartography, golf-sports, government, healthcare, hospitality, legal, manufacturing, nams-default, oil-gas, options-intelligence, personal-knowledge, product-management, real-estate, retail-ecommerce, scientific-research, software-engineering, trip-planning, vacation-industry, wildlife-management.