Reasoning and OWL preview
The reasoning and OWL preview API runs reasoning over data that you send in the request. The reasoner checks instances against an ontology, rules, and constraints. The OWL preview parses and classifies OWL documents before you turn them into ontology rules. These calls don't read or change stored ontologies, and they don't check ontology permissions.
Every call needs an Authorization: Bearer <token> header. Request and response field names in this API have no _ prefix. For more information, see AI and reasoning.
This section contains the following API calls:
Run the reasoner
Runs the reasoner over the ontology, rules, constraints, and instances in the request body. The reasoner infers instance types and relationships, and reports constraint violations. A result with violations still returns 200.
An instance belongs to the class it names and to every ancestor of that class. The reasoner builds the class hierarchy from ontology.classes and from subClassOf rules (SubClassOf also works). So a shape, key, or disjointness rule on a class also applies to instances of its subclasses. A property's domain or range only types instances that don't name a class. An instance that names a class keeps it, so a shape's class check can report a wrong relationship target. A key matches only instances that have a value for every key property.
Endpoints
POST /aosvc/api/v1/reasoner/run
Parameters
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
ontology | Object | The classes and relationships. ontology.classes is a list of classes, or a map keyed by class name. Each class has an id, label, or name, and an optional parentClass. A class named by IRI also matches an instance typed with the IRI's local name. An instance of a subclass is also an instance of every ancestor. | Optional |
rules | Array of Object | The rules to apply, such as {"type": "subClassOf", "subClass": "AHU", "superClass": "Entity"} | Optional |
constraints | Object | The constraint shapes, keyed by ID. Each shape is { targetClass, properties[] }. Each property shape has a path and can check minCount, maxCount, datatype, minInclusive, maxInclusive, pattern, and class. | Optional |
instances | Object | The instances, keyed by instance ID. Each instance names its class in type or @type. If both are present, @type wins. | Optional |
engine | String | The engine: builtin, owl, or shacl. Default is builtin. owl returns the builtin results and adds a note that OWL classification isn't run. shacl also runs a SHACL validation pass that adds to violations. | Optional |
Example:
{
"constraints": {
"Pump:tagNumber": {
"targetClass": "Pump",
"properties": [
{ "path": "tagNumber", "minCount": 1, "datatype": "string" }
]
}
},
"instances": {
"pump-1": { "type": "Pump", "tagNumber": 42 }
}
}
Response
| Field | Description |
|---|---|
inferences | The derived facts. With the owl or shacl engine, this also has EngineMode notes. |
violations | The constraint failures, each with a type, severity, instance, message, and the shape ID where one applies |
relationships | The resolved relationships, each with a source, property, and target |
instanceTypes | A map of instance ID to its types |
{
"inferences": [
{
"type": "ClassInference",
"instance": "pump-1",
"message": "pump-1 is a Pump",
"reason": "@type assertion",
"axiom": "Pump"
}
],
"violations": [
{
"type": "SHACLViolation",
"severity": "Error",
"instance": "pump-1",
"message": "sh:datatype string on 'tagNumber' — found 42 for pump-1",
"shape": "Pump:tagNumber"
}
],
"relationships": [],
"instanceTypes": {
"pump-1": ["Pump"]
}
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing, or the body is missing or malformed. |
401 | Unauthorized |
Preview OWL documents
Parses and classifies OWL documents that you send inline, and returns their axioms. Nothing is saved. To keep axioms, create rules from them with the rules API.
Your nsfilter must resolve to exactly one namespace.
Endpoints
POST /aosvc/api/v1/source/owl/preview
Parameters
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must resolve to exactly one namespace. Two namespaces are refused, whether you send them comma-separated or as repeated nsfilter parameters. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
contractVersion | Number | The contract version. Must be 1. | Required |
documents | Array of Object | The documents to parse. The array can't be empty. | Required |
documents[].name | String | The document name, used in diagnostics and provenance | Required |
documents[].content | String | The document text | Required |
documents[].mediaType | String | A format hint, such as text/turtle, text/owl-functional, or application/rdf+xml | Optional |
reasoner | String | The reasoner: AUTO, ELK, HERMIT, STRUCTURAL, or NONE. Default is AUTO. | Optional |
includeInferred | Boolean | Whether to also return inferred axioms. Default is true. | Optional |
loadAllowlistedRemoteImports | Boolean | Whether to follow owl:imports to allowlisted hosts. The server must also allow remote imports. Default is false. | Optional |
options | Object | An alternative way to send reasoner, includeInferred, and loadAllowlistedRemoteImports | Optional |
Example:
{
"contractVersion": 1,
"reasoner": "ELK",
"includeInferred": true,
"documents": [
{
"name": "selected.ofn",
"mediaType": "text/owl-functional",
"content": "Prefix(:=<urn:example#>) Ontology(Declaration(Class(:Pump)) Declaration(Class(:Asset)) SubClassOf(:Pump :Asset))"
}
]
}
Response
| Field | Description |
|---|---|
classification | The requestedReasoner, the reasoner actually used, implementation, consistent, unsatisfiableClasses, and elapsedMillis. The reasoner used can differ from the one requested. |
profile | The OWL 2 profile: name, supported, and profiles |
counts | Counts of documents, axioms, imports, diagnostics, and unsatisfiable classes |
axioms | The axioms. Each has an id that you can pass to Explain a previewed axiom, plus origin (ASSERTED or INFERRED), owlAxiomType, functionalSyntax, display, persistenceDisposition, and explanationAvailable. A NATIVE axiom has a nativeRule, and a GENERIC axiom has a genericRule, that you can send to the rules API. |
imports | The imports: iri, document, status, message, blocking, depth, and resolvedDocument |
diagnostics | The parse and classification messages: severity, code, document, message, and blocking |
limits | The limits that applied, and truncated if the axiom list was cut |
{
"contractVersion": 1,
"classification": {
"requestedReasoner": "ELK",
"reasoner": "ELK",
"implementation": "ELK 0.6.0",
"consistent": true,
"unsatisfiableClasses": [],
"elapsedMillis": 41
},
"profile": {
"name": "OWL 2 EL",
"supported": true,
"profiles": ["OWL 2", "OWL 2 DL", "OWL 2 EL", "OWL 2 QL", "OWL 2 RL"]
},
"counts": {
"documents": 1,
"selectedDocuments": 1,
"importedDocuments": 0,
"axioms": 3,
"assertedAxioms": 3,
"inferredAxioms": 0,
"imports": 0,
"diagnostics": 0,
"unsatisfiableClasses": 0
},
"axioms": [
{
"id": "owlax-3f9a1c0e7b2d4a6c8e1f0a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"origin": "ASSERTED",
"owlAxiomType": "SubClassOf",
"functionalSyntax": "SubClassOf(<urn:example#Pump> <urn:example#Asset>)",
"display": "SubClassOf(<urn:example#Pump> <urn:example#Asset>)",
"dependencies": [],
"provenance": {
"documents": ["selected.ofn"],
"imported": false,
"document": "selected.ofn"
},
"persistenceDisposition": "NATIVE",
"nativeRule": {
"subClass": "Pump",
"subClassIri": "urn:example#Pump",
"superClass": "Asset",
"superClassIri": "urn:example#Asset",
"type": "SubClassOf"
},
"genericRule": null,
"explanationAvailable": false
}
],
"imports": [],
"diagnostics": [],
"limits": {
"maxDocuments": 32,
"maxDocumentBytes": 4194304,
"maxTotalBytes": 16777216,
"maxAssertedAxioms": 10000,
"maxInferredAxioms": 10000,
"classificationTimeoutMillis": 10000,
"maxImportDocuments": 8,
"maxImportDocumentBytes": 524288,
"maxImportTotalBytes": 2097152,
"maxImportDepth": 4,
"maxImportRedirects": 2,
"maxExplanationDepth": 12,
"maxExplanationVisitedClasses": 256,
"maxExplanationGraphEdges": 4096,
"truncated": false
}
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing or doesn't resolve to exactly one namespace, the request is invalid, contractVersion isn't 1, or the OWL is malformed. |
401 | Unauthorized |
413 | Payload Too Large. A document or the whole request is over the size limit. |
422 | Unprocessable Entity. The documents parse, but use constructs the reasoner doesn't support. |
503 | Service Unavailable. No classification capacity is free. Try again later. |
504 | Gateway Timeout. Classification took longer than its time limit. |
Explain a previewed axiom
Explains one inferred axiom from an OWL preview by returning the asserted axioms that support it. The platform doesn't keep preview results, so send the full preview request again in preview.
If no explanation is found, the call still returns 200 with available set to false and a reason.
Endpoints
POST /aosvc/api/v1/source/owl/explain
Parameters
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must resolve to exactly one namespace. Two namespaces are refused, whether you send them comma-separated or as repeated nsfilter parameters. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
contractVersion | Number | The contract version. Must be 1. | Required |
axiomId | String | An axiom id from the Preview OWL documents response | Required |
preview | Object | The full request body you sent to Preview OWL documents | Required |
Example:
{
"contractVersion": 1,
"axiomId": "owlax-3f9a1c0e7b2d4a6c8e1f0a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"preview": {
"contractVersion": 1,
"reasoner": "ELK",
"documents": [
{
"name": "selected.ofn",
"mediaType": "text/owl-functional",
"content": "Prefix(:=<urn:example#>) Ontology(Declaration(Class(:Pump)) Declaration(Class(:Asset)) SubClassOf(:Pump :Asset))"
}
]
}
}
Response
| Field | Description |
|---|---|
axiomId | The axiom ID you sent |
available | Whether an explanation was found |
reason | Why no explanation is available, when available is false |
reasoner | The reasoner used |
implementation | The reasoner implementation |
supportingAxiomIds | The asserted axiom IDs that support the inference, in order |
{
"contractVersion": 1,
"axiomId": "owlax-3f9a1c0e7b2d4a6c8e1f0a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"available": true,
"reason": "Deterministic shortest asserted named-subclass path",
"reasoner": "ELK",
"implementation": "ELK 0.6.0",
"supportingAxiomIds": [
"owlax-3f9a1c0e7b2d4a6c8e1f0a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"owlax-8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a"
]
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing or doesn't resolve to exactly one namespace, axiomId or preview is missing, axiomId isn't in the preview, contractVersion isn't 1, or the OWL is malformed. |
401 | Unauthorized |
413 | Payload Too Large. A document or the whole request is over the size limit. |
422 | Unprocessable Entity. The documents parse, but use constructs the reasoner doesn't support. |
503 | Service Unavailable. No classification capacity is free. Try again later. |
504 | Gateway Timeout. Classification took longer than its time limit. |