Skip to main content
Version: v5.3

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 architecture

Application Ontology Service concepts​

Refer to the table below for the most important Application Ontology Service terms:

TermDescription
OntologyThe application ontology of a namespace. It holds your classes, relationships, rules, constraints, collection mappings, and state machines. For more information, see Ontologies.
Base ontologyThe 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.
VersionA numbered copy of an ontology's schema. A version is a draft, published, or promoted. For more information, see Versions and drafts.
DraftA version you can still change. Every schema change goes into a draft. For more information, see Versions and drafts.
Live versionThe promoted version that reads and individuals use by default. For more information, see Versions and drafts.
ClassA kind of thing in your domain, such as Pump. Every class extends a base class or another class. For more information, see Classes.
Class relationshipA declaration that individuals of one class can point at individuals of another, such as Pump locatedAt Room. For more information, see Class relationships.
RuleA statement about classes and properties, such as an inverse property, a unique key, or mutually exclusive classes. For more information, see Rules.
ConstraintA shape that individuals of a class must meet, such as "exactly one tag number". For more information, see Constraints.
Collection mappingThe binding between a class and the Item Service collection that stores its individuals. For more information, see Collection mapping.
IndividualOne instance of a class, such as a specific pump, stored as an item in the class's collection. For more information, see Individuals.
External keyThe fields whose values identify an individual in its source system. Import uses them to match existing individuals. For more information, see External keys.
Individual relationshipA link from one individual to others along a declared class relationship. For more information, see Individual relationships.
State machineThe states, events, and transitions of the individuals of one or more classes. For more information, see State machines.
ActionA named side effect, such as running a script or starting a workflow, that runs when a transition fires. For more information, see Actions.
ImportA queued request that creates or updates individuals across several classes and links them by their external keys. For more information, see Importing individuals.
Async taskA 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.
PermissionA 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.