Ontologies
An Ontology is a named group of Entity Types. It describes one domain of your data: the Entity Types in it, the relations between them, where their records come from, and documents that explain them.
Ontologies are managed in Operator, in the Entity Types area, where the Entity Type tree is grouped by Ontology and each Ontology has a diagram and a list of documents. In Navigator, Ask Nextspace scopes a conversation to one Ontology.
This article will cover how to manage Ontology records, how Entity Types belong to one, how to read the diagram of an Ontology in one request, and how to attach documents to it.
Data model
Below is the core data model for an Ontology. The record itself holds no list of Entity Types; each Entity Type names its Ontology instead.
Entity Types in an Ontology
An Entity Type joins an Ontology through its "Ontology.ID" value. An Entity Type belongs to at most one Ontology. Entity Types with no "Ontology.ID" are shown in Operator under "Default Ontology", which is not a record and has no ID.
Child Entity Types follow their parent. An Entity Type whose own "Ontology.ID" is empty counts as part of its parent's Ontology when we work out an Ontology's members for its diagram, up to 10 levels down. A child that names a different Ontology belongs to that one instead. When you change an Entity Type's Ontology in Operator, Operator also writes the same "Ontology.ID" to each of its descendants.
You can list the Entity Types tagged with an Ontology through the Entity Types request with "Ontology.ID={ontology_id}". That filter matches the "Ontology.ID" value only, and like the other filters it also returns the parents of each match. To get the full membership with inherited children, use the connections request below. You can read about Entity Types in Entity Types.
Deleting an Ontology does not delete its Entity Types. Their "Ontology.ID" is cleared, so they move to the Default Ontology.
Requesting records
You can request a list of all Ontologies, ordered by name, or a single Ontology by ID. Each request checks the account's Ontology permissions.
Get a list of Ontologies
Get Ontology by ID
Create and update records
You can create a record by performing a POST request to the same URL as the GET. If you specify the ID as "0" then it'll create a new record and return it. If you specify an existing ID then it'll update the record and return it. An ID that does not exist returns a 404.
When updating, only the properties you include are changed. "Diagram" and "Settings" are replaced as a whole.
Create or update Ontology
Delete a record
We don't provide any bulk deletion but you can delete by record ID. Deleting an ID that does not exist still succeeds. Deleting an Ontology also deletes its document links, but not the files they point at.
Delete Ontology
Ontology connections
The connections request returns every record an Ontology diagram draws, in one response. Operator's diagram is built from it. The Entity Types in scope are the Ontology's members as described above, and only those the user may view.
An Ontology is a closed set: the response holds the relations, sources and dependencies between its members, and an edge to an Entity Type outside it is left out.
Get Ontology connections
A second form reads the same response for views that have no Ontology record: the Default Ontology, or a walk out from chosen Entity Types. You must give at least one of "Ontology.ID", "Unassigned" or "EntityType.ID". A walk from "EntityType.ID" follows relations, sources and child Entity Types for "Depth" steps. Children of the file container types "IFC", "BRZ", "ASSEMBLY", "DWG", "DXF", "PLANT3DZ" and "NWD" are only followed when you name that Entity Type yourself. "Ontology.ID" and "Unassigned" return their members only and are not walked out from.
Get connections by query
Diagram layout
Operator saves the layout of an Ontology diagram in the Ontology's "Diagram" value, and the layout of an Entity Type's own diagram in that Entity Type's "OntologyDiagramSettings". Both hold the same structure. Nodes without a saved position are laid out automatically.
To save an Entity Type's diagram layout without saving the rest of the Entity Type, use the request below. It needs permission to edit the Entity Type. To read it back, request the Entity Type with "Expand=OntologyDiagramSettings".
Save Entity Type diagram layout
Documents
A document link attaches a Client File to an Ontology, usually a PDF or a Markdown file that explains the domain. A PDF can also link a Markdown summary of itself. Ask Nextspace reads the documents whose "Purpose" is "AI", and Operator uses "AI" unless you enter another Purpose. You can read about Client Files in Client and temp files.
A summary is outdated once the PDF is replaced with a new version. Replacing the PDF and linking a new summary are two separate saves: save the new PDF first, then link a summary made from it.
Documents: Requests
You can list the document links of an Ontology, or find the links that use a Client File as the document or as the summary. Give exactly one of the query parameters.
Get a list of Ontology documents
Saving a link needs permission to edit the Ontology and to view the Client Files. Without an "ID", a link with the same "Ontology.ID", "ClientFile.ID" and "Purpose" is updated rather than duplicated. Keys you leave out of the body are left unchanged.
Create or update Ontology document
Deleting a link does not delete its Client Files. Deleting an ID that does not exist still succeeds.
Delete Ontology document
Before generating a summary, Operator checks the source with the request below. It needs permission to edit the Ontology, and fails if the document is not a PDF.
Get document summary source
Describe with AI
The describe request asks the account's AI provider to write a Markdown description of an Ontology. We send it the Ontology's tagged Entity Types, every Entity Type reachable from them through Entity Type relations, and their sources. The response is the Markdown text itself, not JSON. Operator's "Suggest ontology document" uses it to draft a new document. If the account has no AI key configured, it returns a 503 with "AINotConfigured".
Describe Ontology
Ask Nextspace
Navigator's Ask Nextspace scopes each conversation to one Ontology, or to none. The user can pick one from the chat menu. Otherwise the Project View's default applies, set in its "llms.ontologyId" setting. You can read about that setting in Project Views.
With an Ontology in scope, the assistant is given that Ontology's Entity Type hierarchy and a list of its "AI" documents, which it reads when a question needs them. A current PDF summary is offered alongside its PDF. When neither the user nor the Project View sets an Ontology, the assistant may pick one for that message only, and nothing is saved.
AI tools in Operator
Operator offers these AI tools around Ontologies. Each produces a draft for you to review, and nothing is saved until you choose to save it.
- Suggest ontology document: drafts a Markdown document from the describe request above.
- Generate AI summary: drafts a Markdown summary of a PDF document through Operator's chat service. Saving it uploads the Markdown as a Client File and links it as "SummaryClientFile.ID".
- Convert ontology: on a diagram, suggests how the shown Entity Types map onto another Entity Type hierarchy, through "entityType/ontology/aiSuggestOptimisation".
- Unify ontology sources: on a diagram, suggests one Data Schema and mapping for the shown Entity Types, through "v1/entityType/DataSchema/SuggestUnification".