Skip to main content
Version: v5.3

Constraints

Constraints​

A constraint describes what the individuals of a class must contain. It's a property shape over one class: a list of properties, each with limits on how many values it has and what those values look like. For example, a constraint on Pump can say that every pump has exactly one tagNumber, and that it's a string.

A constraint applies to individuals of its target class and all its subclasses. You can target one of your classes or a base class such as Entity. To see every constraint that applies to a class, read the class's effective schema.

Each constraint has a label that you choose, such as Pump:tagNumber. The label is unique in the ontology version and can't change. Don't reuse a base constraint label such as Shape_Entity, because your constraint then replaces the base one.

You add, change, and delete constraints in a draft. They take effect when you promote the version. For more information, see Versions and drafts.

Note: For the constraint fields, refer to the Create constraints and Update a constraint Rest API sections.

Individual validation​

The service checks each individual against the constraints of its class every time you create or update it. The check combines your constraints with the base ontology's constraints for the live version. If an individual fails, the write fails with 422 and the response lists the violations. When you create several individuals in one call, nothing is stored if any of them fails.

When you import individuals, you choose how strictly the service checks value facets, such as datatype, range, and pattern:

  • ENFORCE, the default, rejects individuals that fail a value facet.
  • REPORT turns value-facet failures into warnings.

Count facets, minCount and maxCount, are always enforced. For more information, see Importing individuals.

The service doesn't check existing individuals again when you change a constraint. To find data that the new constraints would reject, send it to the validation call before you promote.

Note: For more information, refer to the Create individuals, Import individuals, and Validate data against an ontology Rest API sections.

Constraint facets​

A constraint's shape is a JSON object with a properties array, which you send encoded as a string in _constraintsJson. Each entry names a property in path and sets one or more facets:

{
"properties": [
{ "path": "tagNumber", "minCount": 1, "maxCount": 1, "datatype": "string" },
{ "path": "nominalFlowRate", "datatype": "decimal", "minInclusive": 0 }
]
}
FacetKindDescription
pathThe property name. An entry with no path is skipped.
minCountCountThe minimum number of values.
maxCountCountThe maximum number of values.
datatypeValueThe value type, for example string, integer, decimal, boolean, dateTime, or anyURI.
minInclusiveValueThe smallest allowed number.
maxInclusiveValueThe largest allowed number.
patternValueA regular expression the value must match. A value over 10000 characters, or a match that takes over 100 ms, fails.
classValueThe class a relationship target must be an instance of. The service doesn't check it when you write individuals.