Skip to main content
Version: v5.3

Impact reports

Use the Impact reports API to see what would change if a version of an ontology replaced the live version. A report compares a draft or published version with the live version and marks each change SAFE, ATTENTION, or BREAKING. Every request needs an Authorization: Bearer <token> header and READ permission on the ontology. For background, see Versions and drafts.

A new report starts as PENDING. A background task fills it in and sets it to READY, or to FAILED with a _failureReason. When you request a promotion, the service requests a report for you.

This section contains the following API calls:

Request an impact report​

Requests a report that compares a version with the live version. Name the version by number or by version ID. If you send both, they must name the same version.

If a PENDING or READY report for the same pair of versions already exists, the call returns it with 200 instead of creating a new one. A report on a draft is reused only while the draft is unchanged. A report on a published or promoted version is reused only if it was created after the version was published. A FAILED report is never reused, so to retry, request again.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/impact-analysis-reports

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_versionFromIntegerThe number of the version to compare. Required unless you send _versionFromId.Optional
_versionFromIdStringThe ID of the version to compare, in the form <ontologyId>:v<number>. Required unless you send _versionFrom.Optional

Example:

{
"_versionFrom": 3
}

Response​

{
"_id": "7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47",
"_ontologyId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2",
"_name": "Ontology Impact Analysis Report — v3 to live v2",
"_status": "PENDING",
"_versionFrom": 3,
"_versionFromId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3",
"_versionTo": 2,
"_versionToId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v2",
"_createdAt": "2026-09-22T14:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedAt": "2026-09-22T14:00:00Z",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
FieldDescription
_statusPENDING, READY, or FAILED.
_versionFrom, _versionFromIdThe version being compared.
_versionTo, _versionToIdThe version that was live when you requested the report.
_reportThe report content. Present only when the report is READY, and only from Get an impact report.
_failureReasonWhy the report failed. Present only when the report is FAILED.

Codes​

CodeDescription
200Success. An existing report is returned.
201Created. A new PENDING report is returned.
400Bad Request. No version is named, _versionFrom is below 1, the two fields name different versions, the version is the live one or is still being copied, or nothing is live.
403Forbidden
404Not Found. The ontology or version is unknown, or the version ID belongs to another ontology.
503Service Unavailable. The report couldn't be queued and is saved as FAILED. Request again.

List impact reports​

Lists the ontology's reports, newest first. The entries don't include _report.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/impact-analysis-reports

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required
queryObjectA JSON filter on report fields, raw or URL-encoded. Name fields as the API returns them, including fields inside the report such as _report._verdict._breaking. Use a bare value for equality, or the operators $eq, $ne, $gt, $gte, $lt, $lte, $in, and $nin. _createdAt and _updatedAt take ISO 8601 timestamps. Other operators return 400.Optional
_offsetIntegerThe position to start listing from. Default is 0.Optional
_pageSizeIntegerThe number of reports per page. Default and maximum is 50.Optional

Example request:

GET /aosvc/api/v1/ontologies/d4721098-9c7f-4e7d-84f4-84bea8f21ca2/impact-analysis-reports?nsfilter=myapp_Xw6AQru7&query={"_report._verdict._breaking":{"$gt":0}}

Response​

_pageSize in the response is the number of reports on this page.

{
"_list": [
{
"_id": "7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47",
"_ontologyId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2",
"_name": "Ontology Impact Analysis Report — v3 to live v2",
"_status": "READY",
"_versionFrom": 3,
"_versionFromId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3",
"_versionTo": 2,
"_versionToId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v2",
"_createdAt": "2026-09-22T14:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedAt": "2026-09-22T14:04:00Z",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
],
"_offset": 0,
"_pageSize": 1,
"_total": 1,
"_hasMore": false
}

Codes​

CodeDescription
200Success
400Bad Request. The filter isn't valid.
403Forbidden
404Not Found

Get an impact report​

Returns one report. Poll it until _status is READY, when _report is present. In every change entry, _before is the live version and _after is the version being compared.

_report has three parts:

  • _verdict has the totals. _needAttention is _breaking plus _attention.
  • _diff has one array of changes for each kind of schema: _classes, _relationships, _rules, _checks, _collectionMappings, _propertyMappings, and _aiTools.
  • _stateMachineChanges has one array for each part of a state machine: _stateMachines, _states, _events, _transitions, _transitionEvents, _transitionActions, and _actions.

A part with no changes is left out. Each change entry can have these fields:

FieldDescription
_defIdThe ID of the changed item. It's the same in every version.
_nameThe item's name.
_opadded, removed, or changed.
_severitySAFE, ATTENTION, or BREAKING.
_cosmetictrue when the change can't affect data, for example a new description.
_before, _afterFor a changed item, only the fields that changed. For a removed item, _before is the live item.
_affectedRecords, _affectedLinksThe number of stored records and links the change affects. A missing count means the count is unknown, not zero.
_affectedGrantsPermission grants whose meaning changes.
_referencedByWhat in the compared version still refers to a removed or renamed item.
_conflictsWithAnother item with the same English name. The service refuses duplicate class names, so you don't normally see this field.

Endpoints​

GET /aosvc/api/v1/ontologies/{ontologyId}/impact-analysis-reports/{reportId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology ID.Required
reportIdStringThe report ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the ontology belongs to.Required

Response​

{
"_id": "7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47",
"_ontologyId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2",
"_name": "Ontology Impact Analysis Report — v3 to live v2",
"_status": "READY",
"_versionFrom": 3,
"_versionFromId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3",
"_versionTo": 2,
"_versionToId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v2",
"_report": {
"_verdict": {
"_totalChanges": 14,
"_needAttention": 10,
"_breaking": 6,
"_attention": 4,
"_safe": 4,
"_affectedRecords": 4508
},
"_diff": {
"_classes": [
{
"_defId": "a1c93f02-4b7d-4a11-9e6a-0c2f1d5b8a90",
"_name": "Pump",
"_op": "removed",
"_severity": "BREAKING",
"_affectedRecords": 312,
"_affectedLinks": 58,
"_before": { "_name": { "en": "Pump" } },
"_after": null
}
]
},
"_stateMachineChanges": {
"_states": [
{
"_defId": "43cdc4fc-be08-4a6e-a9b6-8aecd056f4d5",
"_name": "under-repair",
"_op": "removed",
"_severity": "BREAKING",
"_affectedRecords": 2,
"_before": { "_name": "under-repair", "_value": "under-repair" },
"_after": null
}
]
}
},
"_createdAt": "2026-09-22T14:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedAt": "2026-09-22T14:04:00Z",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}

Codes​

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