Skip to main content
Version: v5.3

Ontologies

Use the Ontologies API to create and manage the application ontology for a namespace, read the base platform ontology, control the edit lock, and move an ontology through its versions. Each namespace has at most one application ontology. The nsfilter query parameter selects the namespace, and every request needs an Authorization: Bearer <token> header. For background, see Ontologies.

Ontology schema, that is, classes, relationships, rules, constraints, and mappings, belongs to one version of the ontology:

  • Reads use the live version by default. To read another version, send its number in the X-Ontology-Draft header. Until you promote a first version, nothing is live and reads return empty results.
  • Schema writes must name a draft in the X-Ontology-Draft header. A write without the header, or one that names a published or promoted version, returns 409.
  • A header that names a version the ontology doesn't have returns 404. A header that isn't a positive whole number returns 400.
  • A version moves from DRAFT to PUBLISHED when you publish it, and to PROMOTED, which makes it live, when you confirm a promotion request.

For more information, see Versions and drafts.

Successful reads of an ontology return an ETag header with the ontology's _revision. To make a schema write fail if someone else changed the ontology first, send that value in an If-Match header. A stale value returns 412. To get _name and _description in a particular language, send an Accept-Language header.

This section contains the following API calls:

List ontologies​

Returns the base platform ontology first, then the namespace's application ontology if it exists and you have READ permission on it. If you lack permission, the application ontology is left out of the list.

Endpoints​

GET /aosvc/api/v1/ontologies

Parameters​

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace whose application ontology to list.Required

Response​

[
{
"_id": "_base",
"_namespaces": null,
"_name": "Digital Twin Base Ontology",
"_description": "Core platform entity definitions",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": 0,
"_version": 0,
"_revision": 0,
"_createdAt": null,
"_updatedAt": null,
"_createdBy": null,
"_updatedBy": null
},
{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": -1,
"_version": 1,
"_revision": 12,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-15T14:22:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
FieldDescription
_idThe ontology ID, or _base for the base ontology.
_namespacesThe namespaces the ontology belongs to. null for the base ontology.
_name, _descriptionThe name and description in the language your Accept-Language header selects.
_baseVersionThe base ontology version the ontology builds on.
_editLockTimeoutSecondsThe edit lock lease in seconds. -1 means the ontology doesn't use the edit lock.
_revisionIncreases with every schema change and every promotion. Matches the ETag header.

Codes​

CodeDescription
200Success
400Bad Request
401Unauthorized

Create an ontology​

Creates the application ontology for the namespace. Requires CREATE permission on aosvc:ontology:*. You get all permissions on the new ontology.

The new ontology starts with version 1 as a draft and no live version. Version 1 already contains the platform-managed lifecycle classes State, Event, Action, and StateTransition.

Endpoints​

POST /aosvc/api/v1/ontologies

Parameters​

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace to create the ontology in. A namespace can have only one ontology.Required

Body​

ParameterTypeDescriptionRequired
_nameString or ObjectA name, or a map of language codes to names such as {"en": "Pumps", "de": "Pumpen"}. Each value can't be blank and has a maximum of 255 characters. You can't use Digital Twin Base Ontology.Required
_descriptionString or ObjectA description, or a map of language codes to descriptions. Maximum 10000 characters for each language. To leave it empty, send "", not {}.Optional
_baseVersionStringA base ontology version from List base ontology versions. Default is the latest version.Optional
_editLockTimeoutSecondsIntegerTo protect the ontology with the edit lock, enter the lease in seconds, between 60 and 86400 by default. Default is -1, which turns the edit lock off.Optional

Example:

{
"_name": "Facilities Ontology",
"_description": "Equipment and spaces"
}

Response​

{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": -1,
"_version": 1,
"_revision": 1,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
201Created
400Bad Request. A field value is invalid, or the base version is unknown.
403Forbidden
409Conflict. The namespace already has an ontology, or the name is reserved.
502Bad Gateway. The ontology couldn't be set up and was removed again.

Get an ontology​

Requires READ permission on the ontology.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": -1,
"_version": 1,
"_revision": 12,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-15T14:22:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
304Not Modified. Your If-None-Match header matches the current revision.
403Forbidden
404Not Found

Update an ontology​

Updates the ontology's name, description, or edit lock setting. Omitted fields keep their values. Requires EDIT permission on the ontology and, if the ontology uses the edit lock, the lock. You don't need the X-Ontology-Draft header.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_nameString or ObjectA name, or a map of language codes to names. A map replaces all stored languages, so include every language you want to keep. Same limits as on create.Optional
_descriptionString or ObjectA description, or a map of language codes to descriptions. A map replaces all stored languages.Optional
_editLockTimeoutSecondsIntegerThe edit lock lease in seconds, between 60 and 86400 by default. -1 turns the edit lock off and releases any held lock.Optional

Example:

{
"_name": { "en": "Facilities Ontology", "de": "Gebäudeontologie" },
"_editLockTimeoutSeconds": 1800
}

Response​

{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": 1800,
"_version": 1,
"_revision": 13,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-16T08:10:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found
409Conflict. Someone else holds the edit lock, or the name is reserved.
412Precondition Failed. The If-Match revision is stale.
423Locked. The ontology uses the edit lock and nobody holds it.

Delete an ontology​

Deletes the ontology with all its versions, schema, promotion requests, and impact reports. Requires DELETE permission on the ontology and, if the ontology uses the edit lock, the lock. Item Service collections and their data are not deleted. To delete only one draft, see Discard a draft.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

None.

Codes​

CodeDescription
204No Content
403Forbidden
404Not Found
409Conflict. Someone else holds the edit lock.
423Locked. The ontology uses the edit lock and nobody holds it.

Validate data against an ontology​

Checks the instances you send against the ontology's constraints combined with the base ontology's constraints. Stored individuals aren't checked. Requires READ permission on the ontology. The call validates the live version, or the version you name in X-Ontology-Draft. If the version you name doesn't exist, the call returns 404.

Data that doesn't conform still returns 200. Check the _conforms field.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
dataJsonStringThe array of instances to validate, encoded as a JSON string. This field has no _ prefix.Required

Example:

{
"dataJson": "[{\"type\":\"Pump\",\"entityId\":\"pump-001\",\"entityName\":\"Chiller Pump\"}]"
}

Response​

{
"_conforms": false,
"_violations": [
{
"_focusNode": "Pump",
"_resultPath": "entityName",
"_message": "minCount violation: expected at least 1 value(s) for 'entityName' but found 0",
"_severity": "Violation"
}
]
}

Codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found. The ontology, or the version you name in X-Ontology-Draft, doesn't exist.

List collection mappings​

Lists every class-to-collection mapping in the live version, or in the version you name in X-Ontology-Draft. Mappings of the platform-managed lifecycle classes aren't listed. Requires READ permission on the ontology.

A mapping made by collection name has a null _collectionId until you promote its version. Promotion creates the collection and sets _collectionId to the collection's _userItemId.

Endpoints​

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

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": "6b1f0c2e-3d4a-4b5c-9d8e-7f6a5b4c3d2e",
"_classId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_collectionId": "5cf129f3213fc97f7dbf24fb",
"_collectionName": "Pumps",
"_userType": "Pump",
"_createdAt": "2026-10-01T10:20:00Z",
"_updatedAt": "2026-10-01T10:20:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Get the base ontology​

Returns the three documents of the latest base platform ontology: its classes and properties, its rules, and its constraints. Any authenticated caller can read the base ontology.

Endpoints​

GET /aosvc/api/v1/ontologies/base

Parameters​

Query​

ParameterTypeDescriptionRequired
nsfilterStringYour namespace.Required

Response​

{
"_ontology": {
"classes": {
"Entity": {
"id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"label": "Entity",
"comment": "Base class for all digital twin entities."
}
},
"properties": {}
},
"_rules": [
{
"type": "relationship_rule",
"property": "fromState",
"fromClass": "StateTransition",
"toClass": "State",
"required": true
}
],
"_constraints": {
"Entity": {
"targetClass": "Entity",
"properties": [
{ "path": "entityId", "minCount": 1, "maxCount": 1, "datatype": "string" }
]
}
}
}

The example is shortened. Each document is returned in full.

Codes​

CodeDescription
200Success
401Unauthorized

List base ontology versions​

Lists the available base ontology versions, newest first.

Endpoints​

GET /aosvc/api/v1/ontologies/base/versions

Parameters​

Query​

ParameterTypeDescriptionRequired
nsfilterStringYour namespace.Required

Response​

[
{ "_version": "1.0.0", "_latest": true }
]

Codes​

CodeDescription
200Success
401Unauthorized

List base ontology classes​

Lists the core classes of the base ontology. Your application classes extend these classes. To get the full schema of a base class, see Get the effective schema of a class.

Endpoints​

GET /aosvc/api/v1/ontologies/base/classes

Parameters​

Query​

ParameterTypeDescriptionRequired
nsfilterStringYour namespace.Required

Response​

[
{
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity",
"_description": "Base class for all digital twin entities.",
"_parentClass": null,
"_extendable": true
}
]
FieldDescription
_idThe class ID. It's the same in every environment.
_parentClassAlways null. Base classes have no parent.
_extendablefalse for the lifecycle classes State, StateTransition, Event, and Action, which you can't extend.

Codes​

CodeDescription
200Success
401Unauthorized

Validate data against the base ontology​

Checks the instances you send against the latest base ontology constraints only. The request and response are the same as for Validate data against an ontology.

Endpoints​

POST /aosvc/api/v1/ontologies/base/validation

Parameters​

Query​

ParameterTypeDescriptionRequired
nsfilterStringYour namespace.Required

Body​

ParameterTypeDescriptionRequired
dataJsonStringThe array of instances to validate, encoded as a JSON string.Required

Example:

{
"dataJson": "[{\"type\":\"Entity\",\"entityId\":\"e-001\",\"entityName\":\"Boiler\"}]"
}

Response​

{
"_conforms": true,
"_violations": []
}

Codes​

CodeDescription
200Success
400Bad Request

Get the edit lock​

Returns who holds the ontology's edit lock and until when. Requires READ permission on the ontology.

The edit lock is off unless the ontology's _editLockTimeoutSeconds is set. When it's on, you must hold the lock to change the ontology, its classes, relationships, rules, constraints, actions, or state machines. Writing individuals and other data never needs the lock. The lease runs from your last activity, and your schema writes extend it.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": true,
"_holder": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_holderName": "Jane Smith",
"_acquiredAt": "2026-10-01T09:00:00Z",
"_lastActivityAt": "2026-10-01T09:12:00Z",
"_expiresAt": "2026-10-01T09:42:00Z",
"_heldByMe": true,
"_lastWriteBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_changedByAnother": false,
"_lockingEnabled": true,
"_leaseSeconds": 1800
}
FieldDescription
_lockingEnabledWhether the ontology uses the edit lock. If false, the response contains only _ontologyId, _lockingEnabled, _locked, and _leaseSeconds (-1).
_lockedWhether someone holds the lock.
_holder, _holderNameThe ID and display name of the lock holder.
_heldByMeWhether you hold the lock.
_lastWriteBy, _changedByAnotherWho made the last schema change, and whether it was someone other than you.
_leaseSecondsThe lease length in seconds.

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Acquire the edit lock​

Takes the edit lock. If you already hold it, the call extends the lease. Requires EDIT permission on the ontology. There's no queue: if someone else holds the lock, the call fails.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

The response has the same fields as Get the edit lock.

{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": true,
"_holder": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_holderName": "Jane Smith",
"_acquiredAt": "2026-10-01T09:00:00Z",
"_lastActivityAt": "2026-10-01T09:00:00Z",
"_expiresAt": "2026-10-01T09:30:00Z",
"_heldByMe": true,
"_lastWriteBy": null,
"_changedByAnother": false,
"_lockingEnabled": true,
"_leaseSeconds": 1800
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found
409Conflict. Someone else holds the lock.

Release the edit lock​

Releases the edit lock if you hold it. Releasing a lock you don't hold isn't an error. To break another user's lock, set force to true.

Endpoints​

DELETE /aosvc/api/v1/ontologies/{ontologyId}/lock

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required
forceBooleanSet to true to release the lock whoever holds it. Requires SHARE permission on the ontology. Without it, the call requires EDIT permission. Default is false.Optional

Response​

{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": false,
"_lastWriteBy": null,
"_changedByAnother": false
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Extend the edit lock​

Extends the lease of a lock you hold without making a change. Use it to keep the lock through a long session with no saves. Requires EDIT permission on the ontology.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/lock/heartbeat

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

The response is the same as for Acquire the edit lock.

{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": true,
"_holder": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_holderName": "Jane Smith",
"_acquiredAt": "2026-10-01T09:00:00Z",
"_lastActivityAt": "2026-10-01T09:25:00Z",
"_expiresAt": "2026-10-01T09:55:00Z",
"_heldByMe": true,
"_lastWriteBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_changedByAnother": false,
"_lockingEnabled": true,
"_leaseSeconds": 1800
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found
409Conflict. Someone else holds the lock.

List versions​

Lists every version of the ontology, oldest first. Requires READ permission on the ontology.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

[
{
"_versionNumber": 1,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v1",
"_status": "PROMOTED",
"_live": true,
"_label": "Initial release",
"_createdAt": "2026-09-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-09-10T11:00:00Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_publishedAt": "2026-09-10T11:00:00Z",
"_promotedAt": "2026-09-10T11:05:00Z"
},
{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "DRAFT",
"_live": false,
"_baseVersionNumber": 1,
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-01T10:14:02Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
FieldDescription
_versionNumberThe version number. Use it in the X-Ontology-Draft header and in version paths.
_statusCOPYING, DRAFT, PUBLISHED, or PROMOTED. Earlier promoted versions keep PROMOTED.
_liveWhether this is the live version.
_baseVersionNumberThe version a draft was copied from.
_labelThe label set when the version was published.
_updatedAtChanges on every write into a draft.

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Get a version​

Returns one version and the number of schema records it holds of each kind. Requires READ permission on the ontology.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/versions/{versionNumber}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
versionNumberIntegerThe version number.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "DRAFT",
"_live": false,
"_baseVersionNumber": 1,
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-01T10:14:02Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_contents": {
"entity_classes": 7,
"entity_relationships": 5,
"ontology_axioms": 2,
"ontology_shapes": 1,
"entity_collection_mappings": 5
}
}

_contents has one entry for each kind of schema record. The example is shortened.

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Create a draft​

Copies a published or promoted version into a new draft with the next free version number. By default, the call copies the live version. Requires EDIT permission on the ontology.

If nothing is live and you don't name a version, the call returns the newest version if it's still a draft.

Endpoints​

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

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

The body is optional.

ParameterTypeDescriptionRequired
_baseVersionNumberIntegerThe version to copy. It must be PUBLISHED or PROMOTED. Default is the live version.Optional

Example:

{
"_baseVersionNumber": 1
}

Response​

{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "DRAFT",
"_live": false,
"_baseVersionNumber": 1,
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-01T08:00:00Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
400Bad Request. _baseVersionNumber is below 1 or doesn't exist.
403Forbidden
404Not Found
409Conflict. The base version isn't published or promoted, nothing is live and no base was named, or another draft was created at the same time. Retry the last case.

Discard a draft​

Deletes a draft and all its schema. Requires EDIT permission on the ontology. You can't discard a published, promoted, or live version. You also can't discard version 1, the draft the ontology starts with. To remove it, publish it or delete the ontology.

Endpoints​

DELETE /aosvc/api/v1/ontologies/{ontologyId}/drafts/{versionNumber}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
versionNumberIntegerThe draft's version number.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

None.

Codes​

CodeDescription
204No Content
403Forbidden
404Not Found
409Conflict. The version isn't a draft, or it's version 1.

Publish a version​

Freezes a draft as PUBLISHED so its schema can't change. Requires EDIT permission on the ontology. Publishing doesn't run any checks.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/versions/{versionNumber}/publish

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
versionNumberIntegerThe draft's version number.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

The body is optional.

ParameterTypeDescriptionRequired
_labelStringA label for the version.Optional

Example:

{
"_label": "2026-10 release"
}

Response​

{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "PUBLISHED",
"_live": false,
"_baseVersionNumber": 1,
"_label": "2026-10 release",
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-02T15:00:00Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_publishedAt": "2026-10-02T15:00:00Z"
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found
409Conflict. The version isn't a draft.

Request a promotion​

Starts promoting a published version so it becomes the live version. Requires EDIT permission on the ontology.

If a version is already live, the call also requests an impact report that compares this version with the live one, and returns its ID in _reportId. A first promotion has no report. An ontology can have only one open promotion request.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_versionNumberIntegerThe published version to promote. Must be a positive whole number.Required

Example:

{
"_versionNumber": 2
}

Response​

{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "REPORT_READY",
"_canConfirm": true,
"_findings": [],
"_rollbackErrors": [],
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
FieldDescription
_fromVersionNumberThe live version when you raised the request. Absent for a first promotion.
_reportIdThe impact report raised with the request. Absent for a first promotion.
_statusREPORT_READY (waiting for you to confirm), CONFIRMING (a confirmation is being applied), PROMOTED, FAILED (the live version didn't change), or ABANDONED. REPORT_READY, CONFIRMING, and FAILED requests are open.
_canConfirmWhether you can confirm the request now. It doesn't mean the impact report is ready.
_findingsWhat stopped the last attempt before it changed anything. Each finding has _check, _severity, and _message. An empty list doesn't mean the version passed other checks.
_taskIdThe background task that applies the promotion, after you confirm it.
_failureReason, _failedAtWhy and when the last attempt failed. Only for FAILED requests.
_rollbackErrorsChanges in Item Service that a failed or abandoned attempt couldn't undo. Fix these by hand. Usually empty.

Codes​

CodeDescription
200Success
400Bad Request. _versionNumber is missing or invalid.
403Forbidden
404Not Found
409Conflict. The version isn't published, is already live, or another request is open.
503Service Unavailable. The impact report couldn't be queued. Nothing was recorded, so try again.

List promotion requests​

Lists the ontology's promotion requests, newest first. Requires READ permission on the ontology.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

The fields are described in Request a promotion.

[
{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "PROMOTED",
"_canConfirm": false,
"_findings": [],
"_rollbackErrors": [],
"_taskId": "d2a4e8f0-1b2c-4d3e-9f8a-7b6c5d4e3f2a",
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_confirmedAt": "2026-10-01T09:20:00Z",
"_confirmedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]

Codes​

CodeDescription
200Success
403Forbidden
404Not Found

Get a promotion request​

Returns one promotion request. After you confirm a promotion, poll this endpoint while _status is CONFIRMING. The request ends as PROMOTED, or as FAILED with _failureReason, _failedAt, and any _rollbackErrors. Requires READ permission on the ontology.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
requestIdStringThe promotion request ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

The fields are described in Request a promotion.

{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "CONFIRMING",
"_canConfirm": false,
"_findings": [],
"_taskId": "d2a4e8f0-1b2c-4d3e-9f8a-7b6c5d4e3f2a",
"_rollbackErrors": [],
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_confirmedAt": "2026-10-01T09:20:00Z",
"_confirmedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found. The request is unknown or belongs to another ontology.

Confirm a promotion​

Applies a promotion request and makes its version live. Requires EDIT permission on the ontology. The promotion runs in the background as you, so the call needs your Authorization header.

The background task registers the version's item types and schemas in Item Service and creates the collections that mappings ask for by name. It then makes the version live. Changes are additive: the promotion never removes an item type or deletes data it didn't create. If the task fails, it undoes its Item Service changes and sets the request to FAILED.

When the new version replaces a live one, the service then updates the class permissions in Item Service to match the new version. Until that update finishes, access granted for the previous version's classes and mappings can remain.

Because the task runs as you, Item Service checks each of its calls against your own Item Service permissions in the namespace. EDIT permission on the ontology lets you confirm, but the task also needs these permissions:

  • READ and EDIT on itemsvc:schemadefinition:*, to read and register item types.
  • CREATE on itemsvc:nameduseritem:*, if a mapping asks for a collection by name.
  • READ and EDIT on each existing collection that a mapping binds to.
  • DELETE on the collections the promotion creates, so it can undo them if it fails.

If you lack one, the request ends as FAILED, and _failureReason quotes the Item Service refusal. Grant the missing permission, then confirm the same request again.

The call returns 202 with no body. Poll the URL in the Location header, which is Get a promotion request, until the request is PROMOTED or FAILED. A FAILED request can be confirmed again to retry, or abandoned. If you confirm a CONFIRMING request again, the call returns 202 and changes nothing.

Some deployments make the version live at once. In that case, the call returns 200 with the promotion request in PROMOTED status. The call also returns 200 with the request if the background task already ended before the call returned. Check _status, which is then PROMOTED or FAILED.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}/confirm

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
requestIdStringThe promotion request ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_reportIdStringThe ID of the request's impact report, which you reviewed. The report must be READY. Required if the request has a report. A first promotion has none.Optional

Example:

{
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f"
}

Response​

None. The response has these headers:

HeaderDescription
LocationThe URL of the promotion request to poll.
X-AOSVC-Reconciliation-Task-IdThe ID of the background task. You can poll it at GET /aosvc/api/v1/async-tasks/{id}, but the outcome of the promotion is on the promotion request.

Codes​

CodeDescription
200Success. The promotion already ended. Check _status in the response.
202Accepted. The promotion is running in the background.
400Bad Request. _reportId is missing for a request that has a report.
401Unauthorized
403Forbidden
404Not Found. The request is unknown or belongs to another ontology.
409Conflict. The request isn't REPORT_READY or FAILED, the version is no longer published, _reportId isn't this request's report, the report isn't READY, the live version changed since the request, or someone else changed the request.
503Service Unavailable. The promotion couldn't be queued. Nothing changed, so try again.

Abandon a promotion request​

Closes an open promotion request so you can promote a different version. Sets a REPORT_READY or FAILED request to ABANDONED and returns it. You can abandon a CONFIRMING request only after its background task has ended without finishing. Requires EDIT permission on the ontology.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}/abandon

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
requestIdStringThe promotion request ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

The fields are described in Request a promotion.

{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "ABANDONED",
"_canConfirm": false,
"_findings": [],
"_rollbackErrors": [],
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}

Codes​

CodeDescription
200Success
403Forbidden
404Not Found
409Conflict. The request isn't open, or its background task can still run.