Application Ontology Service overview
Overview
The Application Ontology Service lets you describe your application's domain as an application ontology: the kinds of things it holds, such as pumps, rooms, and floors, how they relate, and the rules their data must follow. Your application ontology extends the platform's read-only base ontology.
Each namespace has at most one application ontology. You define classes in it, then map each class to an Item Service collection. The individuals of a class, that is, its actual records, are stored as items in that collection. The Application Ontology Service validates every individual against the class's constraints before it stores it.
You change an ontology's schema in a draft version, publish it, and promote it to make it live. Individuals always use the live version.
The Application Ontology Service also provides:
- State machines that track the lifecycle state of individuals, with actions that run when a transition fires.
- Queued import of many individuals across classes in one request.
- Permissions on the ontology and on the individuals of each class, which the service also applies to the Item Service collections that store the individuals.
Figure: Application Ontology Service architecture

Application Ontology Service concepts
Refer to the table below for the most important Application Ontology Service terms:
| Term | Description |
|---|---|
| Ontology | The application ontology of a namespace. It holds your classes, relationships, rules, constraints, collection mappings, and state machines. For more information, see Ontologies. |
| Base ontology | The platform's read-only ontology. It defines base classes such as Entity, EntityGroup, and Telemetry that your classes extend. For more information, see Base ontology. |
| Version | A numbered copy of an ontology's schema. A version is a draft, published, or promoted. For more information, see Versions and drafts. |
| Draft | A version you can still change. Every schema change goes into a draft. For more information, see Versions and drafts. |
| Live version | The promoted version that reads and individuals use by default. For more information, see Versions and drafts. |
| Class | A kind of thing in your domain, such as Pump. Every class extends a base class or another class. For more information, see Classes. |
| Class relationship | A declaration that individuals of one class can point at individuals of another, such as Pump locatedAt Room. For more information, see Class relationships. |
| Rule | A statement about classes and properties, such as an inverse property, a unique key, or mutually exclusive classes. For more information, see Rules. |
| Constraint | A shape that individuals of a class must meet, such as "exactly one tag number". For more information, see Constraints. |
| Collection mapping | The binding between a class and the Item Service collection that stores its individuals. For more information, see Collection mapping. |
| Individual | One instance of a class, such as a specific pump, stored as an item in the class's collection. For more information, see Individuals. |
| External key | The fields whose values identify an individual in its source system. Import uses them to match existing individuals. For more information, see External keys. |
| Individual relationship | A link from one individual to others along a declared class relationship. For more information, see Individual relationships. |
| State machine | The states, events, and transitions of the individuals of one or more classes. For more information, see State machines. |
| Action | A named side effect, such as running a script or starting a workflow, that runs when a transition fires. For more information, see Actions. |
| Import | A queued request that creates or updates individuals across several classes and links them by their external keys. For more information, see Importing individuals. |
| Async task | A background job that a queued call returns. You poll it for the outcome. Imports, bulk relationship loads, and class permission grants return tasks. For more information, see Get an async task. |
| Permission | A grant of actions on an ontology or on the individuals of a class. For more information, see Permissions. |
Calling the Application Ontology Service
Every Application Ontology Service call needs an Authorization: Bearer <token> header and the nsfilter query parameter, which names your namespace. On calls that name an ontology, class, or state machine, nsfilter must name only namespaces that the ontology belongs to. Otherwise, the call returns 404. A call without nsfilter returns 400.
Note: For the Application Ontology Service REST API calls, refer to the Ontologies page and the other pages in the Application Ontology Service REST API section.