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.

interface IOntology {
    // Unique ID for the Ontology.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Required. Limited to 120 characters, longer values are cut.
    Name: string;
    // Description of the Ontology and its purpose.
    Description?: string;
    // Saved layout of the Ontology diagram in Operator.
    // See the Diagram layout section below for the structure.
    Diagram?: IOntologyDiagram;
    // Free JSON object stored with the record.
    // Nothing in Operator, Navigator or Ask Nextspace reads or writes it today.
    Settings?: any;
    // What the requesting user can do with Ontologies.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}

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.

// Only the Ontology fields of an Entity Type are shown here.
interface IEntityType {
    // ID of the Ontology this Entity Type belongs to.
    // Send null or 0 to remove it from its Ontology.
    "Ontology.ID"?: number;
    // Saved layout of the diagram on this Entity Type's own Ontology tab in Operator.
    // Same structure as the Ontology's Diagram. Only returned when requested with Expand.
    OntologyDiagramSettings?: IOntologyDiagram;
}

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

Response
interface IResponse {
    // Array of Ontology records.
    // See the data model above for the record structure.
    Items: IOntology[];
}
Javascript example

Get Ontology by ID

Response
// The response is the Ontology record directly.
// See the data model above for the record structure.
Javascript example

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

Request body
// Body should be the Ontology JSON as specified at the top of the article.
Response
// The response is the Ontology record directly.
// See the data model above for the record structure.
Javascript example

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

Javascript example

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

Response
interface IResponse {
    // The Entity Types in scope, without their Data Schemas.
    "EntityType": IEntityType[];
    // Entity Type relations where both Entity Types are in scope.
    "EntityType.Relation": IEntityTypeRelation[];
    // Where Entity Types get their records from: another Entity Type in scope, or a registered Source.
    // Returned without "DataMapping" and "FilterMapping".
    "EntityType.Source": any[];
    // One row per attribute whose Data Schema dictionary reads values from another Entity Type in scope.
    "EntityType.DictionaryDependency": IDictionaryDependency[];
    // The registered Sources the "EntityType.Source" rows point at.
    "Source": any[];
    // Every Entity Relation Type in the account, to name the relations.
    "EntityRelationType": any[];
    // File imports against the Entity Types in scope. Empty unless IncludeImports is true.
    "FileImport": any[];
}

interface IEntityTypeRelation {
    ID: number;
    "A.EntityType.ID": string;
    "B.EntityType.ID": string;
    // The Entity Relation Type this relation registers.
    "EntityRelationType.ID": string;
    // Attribute paths used as the foreign key on each side.
    "A.ForeignKey.AttributePath"?: string;
    "B.ForeignKey.AttributePath"?: string;
    // How many Entities may sit on side A for one Entity on side B, and the reverse.
    // A maximum of -1 means no limit.
    "A.Cardinality.Min": number;
    "A.Cardinality.Max": number;
    "B.Cardinality.Min": number;
    "B.Cardinality.Max": number;
}

interface IDictionaryDependency {
    // The Entity Type whose attribute uses the dictionary.
    "EntityType.ID": string;
    // The Entity Type the dictionary values come from.
    "Dictionary.EntityType.ID": string;
    // Key of the attribute in the Data Schema.
    "Attribute.Key": string;
}
Javascript example

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

Response
// The response has the same structure as the Ontology connections request above.
Javascript example

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.

interface IOntologyDiagram {
    // Operator writes 1.
    version: 1;
    // Position of each node on the diagram, keyed by node ID.
    nodePositions: Record<string, { x: number; y: number; }>;
    // IDs of the nodes the user has hidden, sorted.
    hiddenNodeIds: string[];
}

// Node IDs are one of:
// An Entity Type ID. Eg: "pipe".
// "external-source:" plus a Source ID, for a live Source.
// "file-source:" plus a Source ID, for a file Source such as CSV, KML or XLSX.
// "imported-file:" plus a file import ID, for an import shown with IncludeImports.

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

Request body
interface IBody {
    OntologyDiagramSettings: IOntologyDiagram;
}
Response
interface IResponse {
    "EntityType.ID": string;
    OntologyDiagramSettings: IOntologyDiagram;
}
Javascript example

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.

interface IOntologyDocument {
    // Unique ID for the document link.
    // Exclude this value for new records.
    ID?: number;
    // ID of the Ontology the document belongs to. Required.
    // It cannot be changed on an existing link.
    "Ontology.ID": number;
    // ID of the document's Client File. Required.
    "ClientFile.ID": string;
    // Label that groups documents by who reads them.
    // Ask Nextspace reads documents with the Purpose "AI".
    Purpose?: string;
    // ID of a Markdown Client File holding a summary of the PDF.
    // Only a PDF document can have one. Send null to unlink it, which keeps the Markdown file.
    "SummaryClientFile.ID"?: string | null;
    // The "Version" of the PDF Client File the summary was made from.
    // When linking a summary it must equal the PDF's current Version.
    // The summary is current only while this matches the PDF's Version.
    SummarySourceVersion?: number | null;
    // Page count of the PDF, counted by the API. Ignored when saving.
    // Missing when the count is unknown or the document is not a PDF.
    SourcePageCount?: number;
    // Returned by the API and ignored when saving.
    ClientFile?: ClientFile.IFile;
    SummaryClientFile?: ClientFile.IFile;
    Ontology?: IOntology;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}

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

Response
interface IResponse {
    // Array of document links.
    // See the documents data model above for the record structure.
    Items: IOntologyDocument[];
}
Javascript example

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

Request body
// Body should be the document JSON as specified in the documents section.
Response
// The response is the document link directly.
// See the documents data model above for the record structure.
Javascript example

Deleting a link does not delete its Client Files. Deleting an ID that does not exist still succeeds.

Delete Ontology document

Javascript example

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

Response
interface IResponse {
    ID: number;
    "Ontology.ID": number;
    "ClientFile.ID": string;
    // The PDF Client File, including its current Version.
    ClientFile: ClientFile.IFile;
}
Javascript example

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

Response
// The response is Markdown text with the content type "text/markdown".
Javascript example

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