Skip to main content
Version: v5.3

Relationships and rules

Class relationships​

A class relationship declares that individuals of one class can point at individuals of another. For example, Pump locatedAt Room lets a pump individual link to the room it's in. The relationship's type, such as locatedAt, is the property name that individuals use for the link.

A class relationship also covers the subclasses at each end. A relationship declared on Equipment lets every Pump use it too.

You declare class relationships in a draft. Individuals then link to each other along them. For more information, see Individual relationships.

You can't declare relationships to or from the lifecycle classes State, Event, Action, and StateTransition.

Note: For the relationship fields, refer to the Create a class relationship Rest API section.

Relationship rules and allowed class pairs​

A relationship_rule limits which classes a relationship type can join. If any relationship_rule exists for a type, a new class relationship of that type must match at least one of them. A rule matches a class by name anywhere in its parent chain, and a rule end that you leave out matches any class. If no rule names the type, any pair of classes is allowed.

The base ontology has relationship rules for its own properties, such as hasMember and telemetryFor. To allow a pair of classes that the base rules don't allow, add your own relationship_rule for the same property.

A relationship_rule is required unless you set "required": false. A required rule means that every individual of the rule's fromClass must have at least one such relationship. Before you add a required rule, declare a class relationship that it covers. You can't delete the last class relationship that a required rule depends on.

Note: For the relationship rules in the base ontology, refer to the Create a class relationship Rest API section.

Rules​

A rule is a statement about your classes and properties, such as "contains and containedBy are inverses" or "Pump and Valve are mutually exclusive". Rules come in two kinds:

  • Inference rules derive new facts from the data you store. For example, an inverse rule means that if room A contains pump B, then pump B is containedBy room A.
  • Checking rules find data that breaks the rule. For example, a unique key rule finds two pumps with the same tag number.

Your rules apply on top of the base ontology's rules. You can read the base rules, but you can't change them.

You add, change, and delete rules in a draft. Rules other than subClassOf name classes and properties by name, not by ID.

Note: For the rule fields and the content of each rule type, refer to the Create rules Rest API section.

Rule enforcement​

The service applies rules at three points:

  • When you change the schema. The service refuses a class relationship that no relationship_rule allows, a required relationship_rule with no matching class relationship, and a class hierarchy with a cycle or a class that inherits from two mutually exclusive classes. These changes return 422.
  • When you write individuals and relationships. A missing relationship that a required relationship_rule asks for, or a functional relationship with more than one target, fails the write with 422.
  • When you run the reasoner. The reasoner applies every rule to a set of individuals. It returns the inferred facts and the rule violations. For more information, see AI assistance and reasoning.

Rules that compare several individuals, such as unique_key and mutually_exclusive, are checked only by the reasoner. A write sees one individual at a time.

Rule types​

Rule typeDescription
subClassOfOne class is a subclass of another.
relationship_ruleA relationship type can join individuals of these classes. Required by default.
inverse_relationshipTwo properties are inverses of each other.
transitiveA property is transitive. If A relates to B, and B relates to C, then A relates to C.
symmetricA property is symmetric. If A relates to B, then B relates to A.
sub_propertyEvery link of one property is also a link of a parent property.
functionalA property has at most one value or target.
unique_keyA set of properties together identifies one individual of a class.
mutually_exclusiveNo individual can belong to more than one of these classes.
owl_axiomAn OWL axiom that no other rule type represents.

Note: To list the rule types, refer to the List rule types Rest API section.