Skip to main content
Version: v5.3

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​

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": "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"
}
]
FieldDescription
_sourceClassId, _targetClassIdThe classes at each end of the relationship.
_typeThe property name, for example locatedAt.
_parameterMapJsonYour own annotation. The service stores and returns it but doesn't use it.
_platformManagedtrue for relationships the platform manages. You can't update or delete them.

Codes​

CodeDescription
200Success
403Forbidden
404Not 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:

PropertyFrom classTo class
hasMemberEntityGroupEntity or EntityGroup
memberOfEntity or EntityGroupEntityGroup
telemetryForTelemetryEntity
relatedTelemetrySoftwareAgentTelemetry
updatedByTelemetrySoftwareAgent
relatedEntitySoftwareAgentEntity
isLinkedToAny classAny 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​

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
_sourceClassIdStringThe source class. It must be in the same version and can't be a lifecycle class.Required
_targetClassIdStringThe target class. It must be in the same version and can't be a lifecycle class.Required
_typeStringThe property name.Required
_descriptionStringA description.Optional
_parameterMapJsonStringYour 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​

CodeDescription
200Success
400Bad Request. A field is missing, or a class is a lifecycle class.
403Forbidden
404Not Found. The ontology, draft, or a class isn't found.
409Conflict. No draft is named, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
422Unprocessable Entity. No relationship_rule for the property allows this pair of classes.
423Locked. 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
relationshipIdStringThe relationship 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
_sourceClassIdStringThe source class.Required
_targetClassIdStringThe target class.Required
_typeStringThe property name.Required
_descriptionStringA description.Optional
_parameterMapJsonStringYour 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​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found
409Conflict. No draft is named, the relationship is platform-managed, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
422Unprocessable Entity. No rule allows the new pair, or a required rule depends on the old relationship.
423Locked. 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
relationshipIdStringThe relationship ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

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

Response​

The response has no body.

Codes​

CodeDescription
204No Content
403Forbidden
404Not Found
409Conflict. No draft is named, the relationship is platform-managed, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
422Unprocessable Entity. A required rule depends on the relationship.
423Locked. 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​

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": "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"
}
]
FieldDescription
_ruleTypeOne of the names from List rule types.
_subClassId, _superClassIdThe two classes of a subClassOf rule.
_ruleJsonThe rule's content for every other rule type, as a string that contains JSON.

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

List rule types​

Lists the ten supported rule types.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/rules/types

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe 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​

CodeDescription
200Success
403Forbidden
404Not 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
ruleIdStringThe rule 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 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​

CodeDescription
200Success
403Forbidden
404Not 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.

_ruleTypeRequired keys in _ruleJsonExample _ruleJson
subClassOfNone. Send _subClassId and _superClassId instead.
relationship_ruleproperty{"property":"locatedAt","fromClass":"Pump","toClass":"Room","required":false}
inverse_relationshipproperty, inverseProperty{"property":"contains","inverseProperty":"containedBy"}
transitive, symmetric, functionalproperty{"property":"contains"}
sub_propertyproperty, parentProperty{"property":"pumpsTo","parentProperty":"feeds"}
unique_keyclass, properties{"class":"Pump","properties":["tagNumber"]}
mutually_exclusiveclasses{"classes":["Pump","Valve"]}
owl_axiomcontractVersion (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​

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
_ruleTypeStringThe rule type.Required
_ruleJsonStringThe rule's content as a JSON object encoded as a string. Required for every type except subClassOf.Optional
_subClassIdStringThe subclass. Required for subClassOf.Optional
_superClassIdStringThe 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​

CodeDescription
200Success
400Bad 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.
403Forbidden
404Not Found
409Conflict. No draft is named, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
413Payload Too Large. An owl_axiom exceeds the size limits.
422Unprocessable Entity. A required relationship_rule has no matching class relationship, or a subClassOf rule creates a cycle or a chain across mutually exclusive classes.
423Locked. 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
ruleIdStringThe rule 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
_ruleTypeStringThe rule type.Optional
_ruleJsonStringThe rule's content as a JSON object encoded as a string.Optional
_subClassIdStringThe subclass of a subClassOf rule.Optional
_superClassIdStringThe 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​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found
409Conflict. No draft is named, or someone else holds the edit lock.
412Precondition Failed. The If-Match revision is stale.
413Payload Too Large. An owl_axiom exceeds the size limits.
422Unprocessable Entity. A required relationship_rule has no matching class relationship, or a subClassOf rule creates a cycle or a chain across mutually exclusive classes.
423Locked. 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
ruleIdStringThe rule ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

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

Response​

The response has no body.

Codes​

CodeDescription
204No Content
403Forbidden
404Not Found
409Conflict. No draft is named, 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.