Skip to main content
Version: v5.3

Constraints

Use the Constraints API to add rules that individuals of a class must meet. A constraint is a property shape over one class: a property path and the count and value limits its values must satisfy. Every request needs an Authorization: Bearer <token> header. For background, see Constraints.

The service combines your constraints with the base ontology's and checks them each time an individual is created or updated. A violation fails the write with 422. Existing individuals aren't checked again when a constraint changes. To see which data would now fail, use Validate data against an ontology.

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.

A constraint has two IDs. _id is the ID you use in paths. _constraintId is your own label, such as Pump:tagNumber, which is unique in the version and can't be changed.

The base ontology's constraints aren't listed or editable here. To read them, see Get the base ontology.

This section contains the following API calls:

List constraints​

Lists the ontology's constraints. The base ontology's constraints aren't included.

Endpoints​

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

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": "8f14e45f-ceea-4e7a-9b1c-2d3e4f5a6b7c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_constraintId": "Pump:tagNumber",
"_targetClass": {
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_name": "Pump"
},
"_constraintsJson": "{\"targetClass\":\"Pump\",\"properties\":[{\"path\":\"tagNumber\",\"minCount\":1,\"maxCount\":1,\"datatype\":\"string\"}]}",
"_description": "Every pump carries exactly one tag number",
"_createdAt": "2026-10-01T09:00:00Z",
"_updatedAt": "2026-10-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
FieldDescription
_constraintIdYour label for the constraint.
_targetClassThe ID and name of the class the constraint applies to. _name is absent if the class is unknown.
_constraintsJsonThe shape, as a string that contains JSON.

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Create constraints​

Adds one constraint or several constraints to a draft. Send an object to add one constraint, and get an object back. Send an array to add several, and get an array back. An array is all or nothing.

A constraint applies to individuals of its target class and all its subclasses, including when the target is a base class such as Entity. To see every constraint that applies to a class, use Get the effective schema of a class. Don't reuse a base constraint label such as Shape_Entity, because your constraint then replaces the base one.

_constraintsJson is a string that contains a JSON object. Keys inside it have no _ prefix:

KeyDescription
targetClassInformational. The service replaces it with the class from _targetClass.
properties[].pathThe property name. A property shape with no path is skipped.
minCount, maxCountThe minimum and maximum number of values.
datatypeThe value type, for example string, integer, decimal, boolean, dateTime, or anyURI.
minInclusive, maxInclusiveThe numeric range.
patternA regular expression the value must match. A value over 10000 characters, or a match that takes over 100 ms, fails.
classThe class a relationship target must be an instance of. Not checked when individuals are written.

Endpoints​

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

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
_constraintIdStringYour label for the constraint. Maximum 255 characters. Must be unique in the version.Required
_targetClassObjectThe class to constrain, as { "_id": "<classId>" }. Use a class in the same version or a base class.Required
_constraintsJsonStringThe shape, as a JSON object encoded as a string. Every pattern must be a valid regular expression.Required
_descriptionStringA description. Maximum 10000 characters.Optional

Example:

{
"_constraintId": "Pump:tagNumber",
"_targetClass": { "_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" },
"_constraintsJson": "{\"targetClass\":\"Pump\",\"properties\":[{\"path\":\"tagNumber\",\"minCount\":1,\"maxCount\":1,\"datatype\":\"string\"}]}",
"_description": "Every pump carries exactly one tag number"
}

Response​

The fields are described in List constraints.

{
"_id": "8f14e45f-ceea-4e7a-9b1c-2d3e4f5a6b7c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_constraintId": "Pump:tagNumber",
"_targetClass": {
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_name": "Pump"
},
"_constraintsJson": "{\"targetClass\":\"Pump\",\"properties\":[{\"path\":\"tagNumber\",\"minCount\":1,\"maxCount\":1,\"datatype\":\"string\"}]}",
"_description": "Every pump carries exactly one tag number",
"_createdAt": "2026-10-01T09:00:00Z",
"_updatedAt": "2026-10-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
400Bad Request. A field is missing or too long, _constraintsJson isn't a JSON object, a pattern isn't valid, or the target class is unknown.
403Forbidden
404Not Found
409Conflict. No draft is named, the _constraintId is already used, 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.

Update a constraint​

Updates a constraint in a draft. Omitted fields keep their values. Fields you send follow the same rules as on create. You can't change _constraintId.

Endpoints​

PUT /aosvc/api/v1/ontologies/{ontologyId}/constraints/{constraintId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
constraintIdStringThe constraint's _id, not its _constraintId label.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Headers​

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

Body​

ParameterTypeDescriptionRequired
_targetClassObjectThe class to constrain, as { "_id": "<classId>" }.Optional
_constraintsJsonStringThe shape, as a JSON object encoded as a string. Can't be blank.Optional
_descriptionStringA description. Maximum 10000 characters.Optional

Example:

{
"_description": "Tag number is mandatory"
}

Response​

The fields are described in List constraints.

{
"_id": "8f14e45f-ceea-4e7a-9b1c-2d3e4f5a6b7c",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_constraintId": "Pump:tagNumber",
"_targetClass": {
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_name": "Pump"
},
"_constraintsJson": "{\"targetClass\":\"Pump\",\"properties\":[{\"path\":\"tagNumber\",\"minCount\":1,\"maxCount\":1,\"datatype\":\"string\"}]}",
"_description": "Tag number is mandatory",
"_createdAt": "2026-10-01T09:00:00Z",
"_updatedAt": "2026-10-02T10:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found. The constraint isn't found, or you used the _constraintId label instead of the _id.
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.

Delete a constraint​

Deletes a constraint from a draft. Deleting an unknown ID also returns 204.

Endpoints​

DELETE /aosvc/api/v1/ontologies/{ontologyId}/constraints/{constraintId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
constraintIdStringThe constraint's _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.