Skip to main content
Version: v5.3

Collection mapping

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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe version number to read. Omit it to read the live version.Optional

Response​

FieldDescription
_collectionIdThe 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.
_collectionNameThe collection name a binding made with _collectionName requested. It is null for a binding made with _collectionId.
_userTypeThe item type of the class's individuals in the collection
_platformManagedtrue 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden
404The 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Body​

ParameterTypeDescriptionRequired
_collectionIdStringThe _userItemId or _id of an existing NamedUserCollection or NamedTelemetryCollection in your namespace. Send this or _collectionName.Optional
_collectionNameStringThe 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
_userTypeStringThe 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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden. You don't have EDIT on the ontology, or you don't have READ on the collection that _collectionId names.
404The class or the named draft is not found
409Conflict. X-Ontology-Draft is missing or does not name an editable draft, or another class in the version already requests the _collectionName.
412The 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Response​

The response has no body.

Codes​

CodeDescription
204No Content
400Bad Request. The class is a platform lifecycle class.
401Unauthorized
403Forbidden
404The class or the named draft is not found
409Conflict. X-Ontology-Draft is missing or does not name an editable draft.
412The 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe 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​

CodeDescription
200Success
401Unauthorized
403Forbidden
404The 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Body​

ParameterTypeDescriptionRequired
_ontologyPropertyStringThe name of the ontology propertyRequired
_itemsvcFieldStringA dot path into the item, for example properties.flowRate. A missing path segment gives no value, not an error. Send this or _script.Optional
_scriptStringScript text. The service stores and returns it but doesn't run it. Send this or _itemsvcField.Optional
_transformStringHow to convert a field value: string, number, boolean, or isoDateOptional

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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden
404The class or the named draft is not found
409Conflict. X-Ontology-Draft is missing or does not name an editable draft.
412The 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired
mappingIdStringThe ID of the property mappingRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Response​

The response has no body.

Codes​

CodeDescription
204No Content
400Bad Request. The class is a platform lifecycle class.
401Unauthorized
403Forbidden
404The class or the named draft is not found
409Conflict. X-Ontology-Draft is missing or does not name an editable draft.
412The If-Match revision is stale