Classes
Classes
A class is a kind of thing in your domain, such as Pump, Floor, or Room. The individuals of a class are its actual records, such as one specific pump. For more information, see Individuals.
A class has an English name that is unique in its ontology version. The name starts with a letter and contains only letters, digits, and underscores. You can add names and descriptions in other languages, and a plural display name. A class keeps the same ID in every version of the ontology.
You create and change classes in a draft. For more information, see Versions and drafts.
To store the individuals of a class, map the class to an Item Service collection. For more information, see Collection mapping.
Note: For the class fields, refer to the Create classes and Update a class Rest API sections.
Class hierarchy
Every class extends a parent class. The parent is either a base ontology class, such as Entity, or another class in the same ontology version. A class inherits the properties and state machines of all its ancestors, and the constraints you declare on them. The base ontology's own constraints apply only to the exact base class, not to classes that extend it.
For example, Pump can extend Equipment, which extends the base class Entity. An individual of Pump is then also an Equipment and an Entity.
The hierarchy also shapes access and queries:
- A permission on a class also covers the individuals of its subclasses. For more information, see Permissions.
- Reading the individuals of a class also returns the individuals of its subclasses.
You can move a class under another parent. This changes the effective schema of the class and all its subclasses, including the constraints that individuals must meet once the version is live. The service refuses a parent that creates a cycle, or one that makes a class inherit from two mutually exclusive classes. This check also counts the parent classes that your subClassOf rules give the class. For more information, see Rules.
To delete a class, first delete or move its subclasses. Deleting a class also deletes its class relationships and its collection and property mappings in the same version. The Item Service collection and its data stay.
The lifecycle classes State, Event, Action, and StateTransition are platform-managed. You can't extend, change, or delete them. For more information, see State machines.
Note: To list the base classes you can extend, refer to the List base ontology classes Rest API section.
External keys
A class's external key fields are the fields whose values identify an individual in its source system, such as an asset tag or a source record ID. When you import individuals, the service matches existing individuals on their external key and updates them instead of creating duplicates. Relationships in an import also find their targets by external key. For more information, see Importing individuals.
Set the external key fields in _externalKeyFields when you create or update the class.
Effective schema
A class's effective schema is everything that applies to an individual of the class, with inheritance resolved. It lists:
- The class's ancestors.
- Every data property and relationship, whether the class declares it or inherits it. If a subclass declares a property with the same name as an ancestor, the subclass's declaration replaces it.
- The constraints that apply to the class and to each property, including the constraints on its ancestors.
- The state machines that apply to the class.
Use the effective schema to see what an individual must contain before you create it, or to check the result after you change a class's parent. You can also read the effective schema of a base class.
Note: For more information, refer to the Get the effective schema of a class Rest API section.