Root classes and class IDs

(Root) classes

A root class, often referred to simply as a class, is a grouping construct associated with a root-level type and all of its derived types, used to improve type legibility and ease service integration.

Each root-level type is assigned a unique ClassId which is then carried through to all classes that derive from it at any level. This allows consumers to easily understand which part of the common type hierarchy that the type belongs to. For example, the root-level type BaseVisualization is assigned the ClassId 5. It has several system-defined types that derive from it, and those types are further derived still, but they all share the same ClassId 5 because they all ultimately derive from BaseVisualization.

The shape of the RootClass object

The RootClass object has just three properties: the classId, the class name, and the ID of the root-level common type it is associated with.

{

"classId": 4,

"name": "Document",

"associatedRootType": "BaseDocument"

}

Defining new root classes

Type Management allows users to define their own classes by creating new root-level types (that is, types whose typeCode is Object and baseTypeId is null). When doing so, you will need to add a unique className property to your request, which Type Management will then use to construct the new root class.

Class name

Class names must be (case-insensitively) unique within the Type Management instance and often are taken from the root type's name (for example, the "Asset" class's associated root type is "BaseAsset").

Why did type management ignore my specified ClassName?

Sometimes users will attempt to specify a className along with a type definition that has a non-null baseTypeId. ClassName is not a valid input field for non-root-level types and so is ignored in this case. Non-root-level types always have the class ID of their parent type.

Class ID

Class ID is a unique, nullable integer value assigned to each root-level object type (common types where TypeCode is Object as opposed to Int32Enum). A type always has the same class ID as its base type, so this class ID is then automatically carried through to all types that derive from it at any level. It allows consumers to easily understand which part of the common type hierarchy that a type belongs to.

System-defined class IDs are in the range of 1-100, whereas user-defined root-level types are assigned values starting at 101. Refer to the table below:

Class IDs for system-defined root types

The system-defined root-level common types have Class IDs that have been assigned by the system:

Extended attributes

Note that there is an additional system-defined root-level type, BaseExtendedAttributes, which is specifically classless, and has a null classId.

Types derived from this base type can be added in combination with any other base type and it does not modify the entity’s class. This allows additional information, such as metadata and context, to be applied to entities of all classes.

This can be useful for some core concepts like location (which could be a type with three properties of latitude, longitude, and elevation), a customer-specific concept of owners, or other applications that do not change the class of the entity itself.

Class IDs for user-defined root-level object types

When a user defines a new root-level common type, the system assigns the next available class ID to that type, starting with 101.

Class IDs for non-root-level object types

A common type's Base Type ID property indicates the ID of the common type it directly inherits from, also called its base or parent type. A common type that does not inherit from any other type is a root-level type and will have a Base Type ID of null.

Root-level types are each assigned a unique class ID. Non-root types have the ClassID of their parent, which will always be the same as the root-level type they ultimately inherit from.

Class ID for enumerated types

An enumerated type (that is, any type that has TypeCode Int32Enum) will always have a Class ID of null.

The Classes API

You can query Type Management for a list of all classes using the top-level /api|ops/v2/classes.

Filtering by Class ID

Root class queries can be filtered just like common type queries using /api|ops/v2/classes?filter=<filter expression>.

Some example queries: