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
| 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": "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"
}
]
| Field | Description |
|---|
_constraintId | Your label for the constraint. |
_targetClass | The ID and name of the class the constraint applies to. _name is absent if the class is unknown. |
_constraintsJson | The shape, as a string that contains JSON. |
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not 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:
| Key | Description |
|---|
targetClass | Informational. The service replaces it with the class from _targetClass. |
properties[].path | The property name. A property shape with no path is skipped. |
minCount, maxCount | The minimum and maximum number of values. |
datatype | The value type, for example string, integer, decimal, boolean, dateTime, or anyURI. |
minInclusive, maxInclusive | The numeric range. |
pattern | A regular expression the value must match. A value over 10000 characters, or a match that takes over 100 ms, fails. |
class | The 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
| 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 |
|---|
_constraintId | String | Your label for the constraint. Maximum 255 characters. Must be unique in the version. | Required |
_targetClass | Object | The class to constrain, as { "_id": "<classId>" }. Use a class in the same version or a base class. | Required |
_constraintsJson | String | The shape, as a JSON object encoded as a string. Every pattern must be a valid regular expression. | Required |
_description | String | A 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
| Code | Description |
|---|
200 | Success |
400 | Bad 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. |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, the _constraintId is already used, 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. |
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
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
constraintId | String | The constraint's _id, not its _constraintId label. | 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 |
|---|
_targetClass | Object | The class to constrain, as { "_id": "<classId>" }. | Optional |
_constraintsJson | String | The shape, as a JSON object encoded as a string. Can't be blank. | Optional |
_description | String | A 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
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
403 | Forbidden |
404 | Not Found. The constraint isn't found, or you used the _constraintId label instead of the _id. |
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. |
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
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
constraintId | String | The constraint's _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. |