Class relationships and rules
Use the Class relationships and rules API to declare which classes can relate to each other, and to add rules to an ontology. A class relationship declares that individuals of one class can point at individuals of another, for example Pump locatedAt Room. A rule is an ontology axiom, such as an inverse property, a transitive property, a unique key, or classes that are mutually exclusive. Every request needs an Authorization: Bearer <token> header. For background, see Relationships and rules.
Reads use the live version unless you name another version in the X-Ontology-Draft header. A read of an ontology with no live version returns []. Writes must name a draft in X-Ontology-Draft. For more information, see Versions and drafts.
Reads require READ permission on the ontology. Writes, including deletes, require EDIT permission and, if the ontology uses the edit lock, 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.
The base ontology's rules aren't listed or editable here. To read them, see Get the base ontology.
This section contains the following API calls:
List class relationships
Lists the ontology's class relationships, with no paging.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/relationships
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Default is the live version. | Optional |
Response
[
{
"_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_sourceClassId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_targetClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_type": "locatedAt",
"_description": "Where this pump is installed",
"_platformManaged": null,
"_createdAt": "2026-10-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
| Field | Description |
|---|
_sourceClassId, _targetClassId | The classes at each end of the relationship. |
_type | The property name, for example locatedAt. |
_parameterMapJson | Your own annotation. The service stores and returns it but doesn't use it. |
_platformManaged | true for relationships the platform manages. You can't update or delete them. |
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Create a class relationship
Declares one class relationship in a draft.
If a relationship_rule exists for the same _type, the relationship must match at least one such rule. A rule's fromClass and toClass match a class by name anywhere in its parent chain, and an omitted end matches any class. If no rule names the _type, any pair of classes is allowed. Duplicate relationships aren't refused.
The base ontology has these relationship rules that you can use between your classes:
| Property | From class | To class |
|---|
hasMember | EntityGroup | Entity or EntityGroup |
memberOf | Entity or EntityGroup | EntityGroup |
telemetryFor | Telemetry | Entity |
relatedTelemetry | SoftwareAgent | Telemetry |
updatedBy | Telemetry | SoftwareAgent |
relatedEntity | SoftwareAgent | Entity |
isLinkedTo | Any class | Any class |
To allow a pair of classes that the base rules don't allow, add your own relationship_rule for the same property.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/relationships
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The draft version number to write to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_sourceClassId | String | The source class. It must be in the same version and can't be a lifecycle class. | Required |
_targetClassId | String | The target class. It must be in the same version and can't be a lifecycle class. | Required |
_type | String | The property name. | Required |
_description | String | A description. | Optional |
_parameterMapJson | String | Your own annotation. Not validated. | Optional |
Example:
{
"_sourceClassId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_targetClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_type": "locatedAt",
"_description": "Where this pump is installed"
}
Response
{
"_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_sourceClassId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_targetClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_type": "locatedAt",
"_description": "Where this pump is installed",
"_createdAt": "2026-10-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. A field is missing, or a class is a lifecycle class. |
403 | Forbidden |
404 | Not Found. The ontology, draft, or a class isn't found. |
409 | Conflict. No draft is named, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
422 | Unprocessable Entity. No relationship_rule for the property allows this pair of classes. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Update a class relationship
Replaces a class relationship in a draft. The body and validation are the same as for Create a class relationship. Optional fields you omit are cleared.
If you change _sourceClassId, _targetClassId, or _type, and a required relationship_rule depends on the old relationship, the call fails with 422.
Endpoints
PUT /aosvc/api/v1/ontologies/{ontologyId}/relationships/{relationshipId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
relationshipId | String | The relationship ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The draft version number to write to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_sourceClassId | String | The source class. | Required |
_targetClassId | String | The target class. | Required |
_type | String | The property name. | Required |
_description | String | A description. | Optional |
_parameterMapJson | String | Your own annotation. | Optional |
Example:
{
"_sourceClassId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_targetClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_type": "locatedAt",
"_description": "The room this pump is installed in"
}
Response
{
"_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_sourceClassId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_targetClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_type": "locatedAt",
"_description": "The room this pump is installed in",
"_createdAt": "2026-10-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, the relationship is platform-managed, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
422 | Unprocessable Entity. No rule allows the new pair, or a required rule depends on the old relationship. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Delete a class relationship
Deletes a class relationship from a draft. Deleting an unknown ID also returns 204. You can't delete the last relationship that a required relationship_rule depends on. Delete the rule first.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/relationships/{relationshipId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
relationshipId | String | The relationship ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The draft version number to write to. | Required |
Response
The response has no body.
Codes
| Code | Description |
|---|
204 | No Content |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, the relationship is platform-managed, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
422 | Unprocessable Entity. A required rule depends on the relationship. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
List rules
Lists the ontology's rules. The base ontology's rules aren't included.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/rules
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Default is the live version. | Optional |
Response
[
{
"_id": "5c9a1b70-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_ruleType": "relationship_rule",
"_ruleJson": "{\"property\":\"locatedAt\",\"fromClass\":\"Pump\",\"toClass\":\"Room\",\"required\":false}",
"_createdAt": "2026-10-01T09:05:00Z",
"_updatedAt": "2026-10-01T09:05:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
| Field | Description |
|---|
_ruleType | One of the names from List rule types. |
_subClassId, _superClassId | The two classes of a subClassOf rule. |
_ruleJson | The rule's content for every other rule type, as a string that contains JSON. |
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
List rule types
Lists the ten supported rule types.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/rules/types
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Response
[
{ "_name": "subClassOf", "_description": "Asserts that one class is a subclass of another" },
{ "_name": "relationship_rule", "_description": "Defines a relationship constraint between classes" },
{ "_name": "inverse_relationship", "_description": "Declares that two object properties are inverses of each other" },
{ "_name": "transitive", "_description": "Marks an object property as transitive" },
{ "_name": "symmetric", "_description": "Marks an object property as symmetric" },
{ "_name": "sub_property", "_description": "Asserts that one property is a sub-property of another" },
{ "_name": "functional", "_description": "Marks an object or data property as functional" },
{ "_name": "unique_key", "_description": "Defines a set of properties that together form a unique key for a class" },
{ "_name": "mutually_exclusive", "_description": "Declares that two or more classes are disjoint (mutually exclusive)" },
{ "_name": "owl_axiom", "_description": "Stores a normalized OWL axiom not represented by a native rule type" }
]
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Get a rule
Returns one rule from the version you read. The call returns a rule only if List rules would list it. A rule ID can't be types.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/rules/{ruleId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
ruleId | String | The rule ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Default is the live version. | Optional |
Response
The fields are described in List rules.
{
"_id": "5c9a1b70-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_ruleType": "relationship_rule",
"_ruleJson": "{\"property\":\"locatedAt\",\"fromClass\":\"Pump\",\"toClass\":\"Room\",\"required\":false}",
"_createdAt": "2026-10-01T09:05:00Z",
"_updatedAt": "2026-10-01T09:05:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found. The rule isn't in the version you read, belongs to another ontology, or nothing is live and you didn't name a version. |
Create rules
Adds one rule or several rules to a draft. Send an object to add one rule, and get an object back. Send an array to add several, and get an array back. The call validates every rule before it writes any, so an array is all or nothing.
_ruleJson is a string that contains a JSON object. Keys inside it have no _ prefix.
_ruleType | Required keys in _ruleJson | Example _ruleJson |
|---|
subClassOf | None. Send _subClassId and _superClassId instead. | |
relationship_rule | property | {"property":"locatedAt","fromClass":"Pump","toClass":"Room","required":false} |
inverse_relationship | property, inverseProperty | {"property":"contains","inverseProperty":"containedBy"} |
transitive, symmetric, functional | property | {"property":"contains"} |
sub_property | property, parentProperty | {"property":"pumpsTo","parentProperty":"feeds"} |
unique_key | class, properties | {"class":"Pump","properties":["tagNumber"]} |
mutually_exclusive | classes | {"classes":["Pump","Valve"]} |
owl_axiom | contractVersion (must be 1), axiomId, axiomType, functionalSyntax | {"contractVersion":1,"axiomId":"ax-1","axiomType":"DisjointClasses","functionalSyntax":"DisjointClasses(ex:Pump ex:Valve)"} |
A relationship_rule is required unless you set "required": false. Before you add a required rule, declare a class relationship that it covers with Create a class relationship.
A subClassOf rule can't create a cycle. The check follows each class's parent, the subClassOf rules already in the version, and earlier rules in the same array. When you update a rule, the check ignores that rule's old content.
An owl_axiom's functionalSyntax must contain exactly one axiom, of the type in axiomType. _ruleJson can be at most 131072 bytes, and functionalSyntax at most 65536 bytes.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/rules
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The draft version number to write to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_ruleType | String | The rule type. | Required |
_ruleJson | String | The rule's content as a JSON object encoded as a string. Required for every type except subClassOf. | Optional |
_subClassId | String | The subclass. Required for subClassOf. | Optional |
_superClassId | String | The parent class. Required for subClassOf. | Optional |
Example:
[
{
"_ruleType": "relationship_rule",
"_ruleJson": "{\"property\":\"locatedAt\",\"fromClass\":\"Pump\",\"toClass\":\"Room\",\"required\":false}"
},
{
"_ruleType": "unique_key",
"_ruleJson": "{\"class\":\"Pump\",\"properties\":[\"tagNumber\"]}"
}
]
Response
[
{
"_id": "5c9a1b70-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_ruleType": "relationship_rule",
"_ruleJson": "{\"property\":\"locatedAt\",\"fromClass\":\"Pump\",\"toClass\":\"Room\",\"required\":false}",
"_createdAt": "2026-10-01T09:05:00Z",
"_updatedAt": "2026-10-01T09:05:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
},
{
"_id": "6d0b2c81-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_ruleType": "unique_key",
"_ruleJson": "{\"class\":\"Pump\",\"properties\":[\"tagNumber\"]}",
"_createdAt": "2026-10-01T09:05:00Z",
"_updatedAt": "2026-10-01T09:05:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. The rule type is unsupported, a required field or key is missing, _ruleJson isn't a JSON object, or an owl_axiom is invalid. |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
413 | Payload Too Large. An owl_axiom exceeds the size limits. |
422 | Unprocessable Entity. A required relationship_rule has no matching class relationship, or a subClassOf rule creates a cycle or a chain across mutually exclusive classes. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Update a rule
Updates a rule in a draft. Omitted fields keep their values, and the call validates the merged rule as on create. Changing a rule to subClassOf clears _ruleJson. Changing it from subClassOf to another type clears both class IDs.
Endpoints
PUT /aosvc/api/v1/ontologies/{ontologyId}/rules/{ruleId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
ruleId | String | The rule ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The draft version number to write to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_ruleType | String | The rule type. | Optional |
_ruleJson | String | The rule's content as a JSON object encoded as a string. | Optional |
_subClassId | String | The subclass of a subClassOf rule. | Optional |
_superClassId | String | The parent class of a subClassOf rule. | Optional |
Example:
{
"_ruleJson": "{\"property\":\"locatedAt\",\"fromClass\":\"Pump\",\"toClass\":\"Room\",\"required\":true}"
}
Response
The fields are described in List rules.
{
"_id": "5c9a1b70-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_ruleType": "relationship_rule",
"_ruleJson": "{\"property\":\"locatedAt\",\"fromClass\":\"Pump\",\"toClass\":\"Room\",\"required\":true}",
"_createdAt": "2026-10-01T09:05:00Z",
"_updatedAt": "2026-10-02T11:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
413 | Payload Too Large. An owl_axiom exceeds the size limits. |
422 | Unprocessable Entity. A required relationship_rule has no matching class relationship, or a subClassOf rule creates a cycle or a chain across mutually exclusive classes. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Delete a rule
Deletes a rule from a draft. Deleting an unknown ID also returns 204.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/rules/{ruleId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
ruleId | String | The rule ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The draft version number to write to. | Required |
Response
The response has no body.
Codes
| Code | Description |
|---|
204 | No Content |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |