Skip to main content
Version: v5.3

Classes

Use the Classes API to create and manage the classes of an application ontology, such as Pump or Floor, and to read a class's effective schema. Every class extends a base platform class or another class in the same ontology version. Every request needs an Authorization: Bearer <token> header. For background, see Classes.

Reads use the live version unless you name another version in the X-Ontology-Draft header. Writes must name a draft in X-Ontology-Draft. For more information, see Versions and drafts.

Writes require EDIT permission on the ontology. If the ontology uses the edit lock, writes also require you to hold the lock. Writes accept an If-Match header with the ontology revision, and return 412 if it's stale. Each successful write returns the new revision in the ETag header. To get _name and _description in a particular language, send an Accept-Language header.

Every ontology contains the platform-managed lifecycle classes State, Event, Action, and StateTransition, marked "_platformManaged": true. You can't update or delete them, or use them as a parent class.

This section contains the following API calls:

List classes​

Lists the classes in the version you read. Requires READ permission on the ontology. Fields with no value are left out.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/classes

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe version number to read. Default is the live version.Optional

Response​

[
{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_parentClass": {
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
FieldDescription
_idThe class ID. It's the same in every version.
_name, _descriptionThe name and description in the language your Accept-Language header selects.
_parentClassThe ID and name of the class this class extends. To find out whether it's a base class, compare it with List base ontology classes.
_pluralNameThe plural display name.
_canvasX, _canvasYThe class's position on a diagram canvas. Stored but not interpreted.
_externalKeyFieldsThe fields whose values identify an individual in its source system.
_platformManagedtrue for the lifecycle classes.

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Create classes​

Creates one class or several classes in a draft. Send an object to create one class, and get an object back. Send an array to create several, and get an array back in the same order. An array is all or nothing: if one class fails, the call creates none of them. A class in the array can extend a class that comes earlier in the same array, so list parent classes before their subclasses.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/classes

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe draft version number to write to.Required

Body​

ParameterTypeDescriptionRequired
_nameString or ObjectA name, or a map of language codes to names. It must have an English (en) value that starts with a letter and contains only letters, digits, and underscores. The English name must be unique in the version. Each value has a maximum of 255 characters.Required
_parentClassObjectThe class to extend, as { "_id": "<classId>" }. Use a base class or a class in the same version. You can't use a lifecycle class.Required
_descriptionString or ObjectA description, or a map of language codes to descriptions. Maximum 10000 characters for each language. Can't be empty: "", {}, or an empty value for any language returns 400.Optional
_pluralNameStringThe plural display name. Same character rules as the English name. Can't be empty.Optional
_canvasX, _canvasYNumberThe class's position on a diagram canvas. An empty string returns 400.Optional
_externalKeyFieldsString[]The fields whose values identify an individual in its source system. Must contain at least one non-blank value.Optional

Example:

{
"_name": "Pump",
"_parentClass": { "_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39" },
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"]
}

Response​

{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_parentClass": {
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
400Bad Request. A field is missing or invalid, or the parent class is unknown or a lifecycle class.
403Forbidden
404Not Found
409Conflict. No draft is named, the English name is already used, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
422Unprocessable Entity. The parent creates a cycle, or a chain across mutually exclusive classes.
423Locked. The ontology uses the edit lock and nobody holds it.

Get a class​

Requires READ permission on the ontology.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
classIdStringThe class ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe version number to read. Default is the live version.Optional

Response​

The fields are described in List classes.

{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_description": "A mechanical pump",
"_parentClass": {
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_updatedAt": "2026-10-01T10:30:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found. The class isn't in the version you read.

Update a class​

Updates a class in a draft. Omitted fields keep their values.

To move the class under another parent, send _parentClass. Changing the parent changes the effective schema of the class and all its subclasses, including the constraints that existing individuals must meet once the version is live. Afterward, check Get the effective schema of a class.

Endpoints​

PUT /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
classIdStringThe class ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe draft version number to write to.Required

Body​

ParameterTypeDescriptionRequired
_nameString or ObjectA name, or a map of language codes to names. A map replaces all stored languages, so include every language you want to keep. Same rules as on create.Optional
_descriptionString or ObjectA description, or a map of language codes to descriptions. Same rules as on create. You can replace a description, but you can't clear it.Optional
_parentClassObjectThe new parent, as { "_id": "<classId>" }. Same rules as on create.Optional
_externalKeyFieldsString[]Replaces the list.Optional
_pluralNameStringThe plural display name. Same rules as on create. You can't clear it.Optional
_canvasX, _canvasYNumberThe class's position on a diagram canvas. An empty string returns 400.Optional

Example:

{
"_description": { "en": "A mechanical pump", "de": "Eine mechanische Pumpe" },
"_parentClass": { "_id": "0b9e7c1a-2d3e-4f5a-8b6c-7d8e9f0a1b2c" }
}

Response​

The fields are described in List classes.

{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_description": "A mechanical pump",
"_parentClass": {
"_id": "0b9e7c1a-2d3e-4f5a-8b6c-7d8e9f0a1b2c",
"_name": "Equipment"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_updatedAt": "2026-10-02T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
400Bad Request. A field is invalid, or _parentClass has no _id.
403Forbidden
404Not Found
409Conflict. No draft is named, the English name is already used, the class is platform-managed, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
422Unprocessable Entity. The new parent creates a cycle, or a chain across mutually exclusive classes. The chain includes the superclasses that the class's own subClassOf rules give it.
423Locked. The ontology uses the edit lock and nobody holds it.

Delete a class​

Deletes a class from a draft. The call also deletes, in the same version, the relationships declared to or from the class and its collection and property mappings. The Item Service collection and its data are not deleted. You can't delete a class that has subclasses. Delete or move the subclasses first.

Endpoints​

DELETE /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
classIdStringThe class ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe draft version number to write to.Required

Response​

None.

Codes​

CodeDescription
204No Content
403Forbidden
404Not Found
409Conflict. No draft is named, the class has subclasses, the class is platform-managed, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
423Locked. The ontology uses the edit lock and nobody holds it.

Get the effective schema of a class​

Returns a class's schema with inheritance resolved: every property, constraint, and state machine that applies to an individual of the class. Requires READ permission on the ontology.

To read a base class schema, use base as the ontologyId. Any authenticated caller can read a base class schema.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}/schema

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID, or base for a base class.Required
classIdStringThe class ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required
inheritedBooleanSet to false to return only what the class declares itself. Default is true.Optional
baseVersionStringFor a base class, the base ontology version. Default is the latest version.Optional

Headers​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe version number to read. Default is the live version.Optional

Response​

{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_classId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_className": "Pump",
"_ancestors": [
{ "_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39", "_name": "Entity", "_base": true }
],
"_properties": [
{
"_name": "entityName",
"_propertyType": "datatype",
"_range": "string",
"_inherited": true,
"_sourceClassName": "Entity",
"_queryPath": "entityName"
},
{
"_name": "nominalFlowRate",
"_propertyType": "datatype",
"_range": "number",
"_inherited": false,
"_sourceClassName": "Pump",
"_itemsvcField": "properties.flowRate",
"_transform": "number",
"_constraints": [ { "path": "nominalFlowRate", "minInclusive": 0 } ]
},
{
"_name": "locatedIn",
"_propertyType": "relationship",
"_range": "Space",
"_rangeClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_inherited": false,
"_relationshipId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}
],
"_constraints": [
{
"targetClass": "Pump",
"properties": [ { "path": "nominalFlowRate", "minInclusive": 0 } ],
"_id": "Pump:nominalFlowRate",
"_targetClass": "Pump"
}
],
"_stateMachines": []
}
FieldDescription
_ontologyIdThe ontology ID, or base for a base class.
_ancestorsThe parent chain. Each entry has _id, _name, and _base, which is true for a base class. Empty for a base class.
_propertiesData properties and relationships in one list. If a subclass declares a property with the same name as an ancestor, the subclass's declaration replaces it.
_properties[]._propertyTypedatatype or relationship.
_properties[]._range, _rangeClassIdThe value type, or the target class of a relationship.
_properties[]._inherited, _sourceClassId, _sourceClassNameWhether the property comes from an ancestor, and which class declares it.
_properties[]._queryPathHow to reference the property in a query.
_properties[]._itemsvcField, _transform, _scriptedHow the property maps from item data, when it's mapped.
_properties[]._relationshipIdThe ID of the relationship that declares the property.
_properties[]._constraintsThe constraint rules for the property, taken from the properties array of each entry in _constraints.
_constraintsThe constraints that apply to the class: those that target the class and, unless inherited is false, those that target its ancestors, including base classes such as Entity. Each entry is the constraint's shape, with _id set to its _constraintId label and _targetClass set to the class name.
_stateMachinesThe state machines that apply to the class. Each has _machineId, _machineName, _sourceClassId, _inherited, _states, and _transitions. Empty for a base class.

Keys with no value are left out. Constraints you declare apply to subclasses too. The base ontology's own constraints apply only to the exact base class.

Codes​

CodeDescription
200Success
400Bad Request. The baseVersion is unknown.
403Forbidden
404Not Found