Skip to main content
Version: v5.3

Ontologies

Application ontologies​

An application ontology describes your application's domain. It holds the classes of things in the domain, the relationships between them, and the rules and constraints their data must follow. It also holds the collection mappings that say where each class's individuals are stored, and the state machines that track their lifecycle.

Each namespace has at most one application ontology. The nsfilter query parameter of a create call sets the ontology's namespace. You don't send it in the body.

An ontology has a name and an optional description. You can send each one as a single string, or as a map of language codes to text, such as {"en": "Pumps", "de": "Pumpen"}. To get the text in a particular language, send an Accept-Language header.

When you create an ontology, you get all permissions on it. To create one, you need CREATE permission on aosvc:ontology:*. For more information, see Permissions.

Deleting an ontology doesn't delete the Item Service collections that store its individuals, or their data.

Note: For the ontology fields, refer to the Create an ontology and Update an ontology Rest API sections.

Base ontology​

The base ontology is the platform's shared foundation. Every application ontology extends it. You can read the base ontology, but you can't change it.

The base ontology defines core classes, such as Entity, EntityGroup, Telemetry, and SoftwareAgent, with their properties, rules, and constraints. Your classes extend these base classes. The base relationship rules also decide which of your classes can relate to each other. For more information, see Class relationships.

The base ontology is versioned. When you create an application ontology, it builds on the latest base version unless you name another. The platform decides which base versions exist. There's no call to switch an ontology to another base version.

The base ontology also defines the lifecycle classes State, Event, Action, and StateTransition. Every application ontology contains them, and the platform manages them. You can't extend, change, or delete them. For more information, see State machines.

Note: To read the base ontology, refer to the Get the base ontology, List base ontology versions, and List base ontology classes Rest API sections.

Ontology lifecycle​

An ontology moves through the following stages:

  • Create: A new ontology starts with version 1 as a draft, and nothing is live.
  • Define: In the draft, you add classes, relationships and rules, constraints, collection mappings, and state machines.
  • Publish and promote: You publish the draft to freeze it, then promote it to make it the live version. Promotion creates the Item Service collections that your mappings ask for.
  • Use: You create, import, and read individuals against the live version.
  • Change: To change the schema later, you create a new draft from the live version and repeat the cycle.

Until you promote the first version, reads of the schema return empty results and calls on individuals fail. For more information, see Versions and drafts.

For a walkthrough, see Creating an ontology.

Ontology validation​

To check data against an ontology without storing it, send the data to the validation call. The service checks it against your constraints combined with the base ontology's constraints. Data that doesn't conform still returns 200, with the violations in the response. Stored individuals aren't checked.

Note: For more information, refer to the Validate data against an ontology and Validate data against the base ontology Rest API sections.