A collection mapping binds a class to the Item Service collection that stores its individuals. A class has at most one collection binding, and any number of property mappings that link item fields to ontology properties. For more information, see Collection mapping.
Mapping writes change only a draft version of the ontology. When you promote the version, the service creates any collection you requested by name and binds it.
Note: Every request needs an Authorization: Bearer <token> header and the nsfilter query parameter. The nsfilter value must name only namespaces the class's ontology belongs to. Otherwise, the service returns 404. Reads need READ on the ontology, and writes need EDIT. For more information, see Permissions.
You can't map the platform classes State, Event, Action, StateTransition, or their subclasses.
This section contains the following API calls:
Get a collection binding
Gets the collection binding of a class.
Endpoints
GET /aosvc/api/v1/classes/{classId}/mapping
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
| Field | Description |
|---|
_collectionId | The ID of the bound collection. For a binding made with _collectionId, it is the ID you sent, either the collection's _userItemId or its _id. For a binding made with _collectionName, it is null until you promote the version, and then it is the _userItemId of the collection that promotion created. |
_collectionName | The collection name a binding made with _collectionName requested. It is null for a binding made with _collectionId. |
_userType | The item type of the class's individuals in the collection |
_platformManaged | true for bindings the platform owns |
{
"_id": "8e2f4a6c-1b3d-4e5f-9a7b-0c2d4e6f8a1b",
"_classId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"_collectionId": "66f2a1c9e4b0a37d5c8e9a10",
"_collectionName": null,
"_userType": "Pump",
"_platformManaged": false,
"_createdAt": "2026-10-01T10:29:00Z",
"_updatedAt": "2026-10-01T10:29:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden |
404 | The class or the named draft is not found, or the class has no binding in the version read |
Bind a class to a collection
Binds a class to a collection in a draft version of the ontology, and replaces any existing binding. Send exactly one of _collectionId and _collectionName:
- To use a collection that already exists, send
_collectionId. You need READ on the collection. The collection can't belong to another platform service, because the Item Service accepts writes to it only from that service. A class that descends from Telemetry needs a NamedTelemetryCollection. If the collection breaks one of these rules, the call fails and the existing binding stays.
- To have the service create a collection when you promote the version, send
_collectionName. The service creates a NamedTelemetryCollection for a class that descends from Telemetry, and a NamedUserCollection for any other class.
Endpoints
POST /aosvc/api/v1/classes/{classId}/mapping
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
_collectionId | String | The _userItemId or _id of an existing NamedUserCollection or NamedTelemetryCollection in your namespace. Send this or _collectionName. | Optional |
_collectionName | String | The name of a collection for the service to create when you promote the version, up to 255 characters. No other class in the same version can request the same name. Send this or _collectionId. | Optional |
_userType | String | The item type of the class's individuals. Default is the class name. | Optional |
Example:
{
"_collectionId": "66f2a1c9e4b0a37d5c8e9a10",
"_userType": "Pump"
}
Response
Returns the binding. The response ETag header holds the new ontology revision.
{
"_id": "8e2f4a6c-1b3d-4e5f-9a7b-0c2d4e6f8a1b",
"_classId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"_collectionId": "66f2a1c9e4b0a37d5c8e9a10",
"_collectionName": null,
"_userType": "Pump",
"_platformManaged": false,
"_createdAt": "2026-10-01T10:29:00Z",
"_updatedAt": "2026-10-01T10:29:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. The body has neither or both of _collectionId and _collectionName, _collectionId is not a named user or telemetry collection in your namespace, belongs to another platform service, or is a NamedUserCollection for a class that descends from Telemetry, _collectionName is over 255 characters, _collectionId, _collectionName or _userType is not a string, or the class is a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden. You don't have EDIT on the ontology, or you don't have READ on the collection that _collectionId names. |
404 | The class or the named draft is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft, or another class in the version already requests the _collectionName. |
412 | The If-Match revision is stale |
Remove a collection binding
Removes the binding and all property mappings of a class from a draft version of the ontology. The collection and its items stay in the Item Service. If the class has no binding, the service still returns 204.
Endpoints
DELETE /aosvc/api/v1/classes/{classId}/mapping
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Response
The response has no body.
Codes
| Code | Description |
|---|
204 | No Content |
400 | Bad Request. The class is a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden |
404 | The class or the named draft is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft. |
412 | The If-Match revision is stale |
List property mappings
Lists the property mappings of a class. The service uses property mappings to check individual writes and imports, and to build the item type schema at promotion. Individual reads return the stored field names, not the mapped property names.
Endpoints
GET /aosvc/api/v1/classes/{classId}/mapping/properties
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
Returns an array of property mappings. _itemsvcField is null for a script mapping, and _script is null for a field mapping. Mappings never change after you add them, so they have no _updatedAt.
[
{
"_id": "2a4c6e8f-0b1d-4f3a-9c5e-7b9d1f3a5c7e",
"_classId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"_itemsvcField": "properties.flowRate",
"_ontologyProperty": "nominalFlowRate",
"_transform": "number",
"_script": null,
"_createdAt": "2026-10-01T10:31:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The class or the named draft is not found |
Add a property mapping
Adds a property mapping to a class in a draft version of the ontology. Send exactly one of _itemsvcField and _script.
Endpoints
POST /aosvc/api/v1/classes/{classId}/mapping/properties
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
_ontologyProperty | String | The name of the ontology property | Required |
_itemsvcField | String | A dot path into the item, for example properties.flowRate. A missing path segment gives no value, not an error. Send this or _script. | Optional |
_script | String | Script text. The service stores and returns it but doesn't run it. Send this or _itemsvcField. | Optional |
_transform | String | How to convert a field value: string, number, boolean, or isoDate | Optional |
Example:
{
"_itemsvcField": "properties.flowRate",
"_ontologyProperty": "nominalFlowRate",
"_transform": "number"
}
Response
Returns the property mapping. The response ETag header holds the new ontology revision.
{
"_id": "2a4c6e8f-0b1d-4f3a-9c5e-7b9d1f3a5c7e",
"_classId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"_itemsvcField": "properties.flowRate",
"_ontologyProperty": "nominalFlowRate",
"_transform": "number",
"_script": null,
"_createdAt": "2026-10-01T10:31:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _ontologyProperty is blank, the body has neither or both of _itemsvcField and _script, _ontologyProperty, _itemsvcField, _transform or _script is not a string, or the class is a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden |
404 | The class or the named draft is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft. |
412 | The If-Match revision is stale |
Delete a property mapping
Deletes one property mapping from a draft version of the ontology. If the mapping doesn't exist or belongs to another class, the service still returns 204.
Endpoints
DELETE /aosvc/api/v1/classes/{classId}/mapping/properties/{mappingId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The ID of the class | Required |
mappingId | String | The ID of the property mapping | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Response
The response has no body.
Codes
| Code | Description |
|---|
204 | No Content |
400 | Bad Request. The class is a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden |
404 | The class or the named draft is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft. |
412 | The If-Match revision is stale |