Skip to main content
Version: v5.3

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​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Body​

ParameterTypeDescriptionRequired
ontologyObjectThe 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
rulesArray of ObjectThe rules to apply, such as {"type": "subClassOf", "subClass": "AHU", "superClass": "Entity"}Optional
constraintsObjectThe 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
instancesObjectThe instances, keyed by instance ID. Each instance names its class in type or @type. If both are present, @type wins.Optional
engineStringThe 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​

FieldDescription
inferencesThe derived facts. With the owl or shacl engine, this also has EngineMode notes.
violationsThe constraint failures, each with a type, severity, instance, message, and the shape ID where one applies
relationshipsThe resolved relationships, each with a source, property, and target
instanceTypesA 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing, or the body is missing or malformed.
401Unauthorized

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​

ParameterTypeDescriptionRequired
nsfilterStringNamespace 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​

ParameterTypeDescriptionRequired
contractVersionNumberThe contract version. Must be 1.Required
documentsArray of ObjectThe documents to parse. The array can't be empty.Required
documents[].nameStringThe document name, used in diagnostics and provenanceRequired
documents[].contentStringThe document textRequired
documents[].mediaTypeStringA format hint, such as text/turtle, text/owl-functional, or application/rdf+xmlOptional
reasonerStringThe reasoner: AUTO, ELK, HERMIT, STRUCTURAL, or NONE. Default is AUTO.Optional
includeInferredBooleanWhether to also return inferred axioms. Default is true.Optional
loadAllowlistedRemoteImportsBooleanWhether to follow owl:imports to allowlisted hosts. The server must also allow remote imports. Default is false.Optional
optionsObjectAn alternative way to send reasoner, includeInferred, and loadAllowlistedRemoteImportsOptional

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​

FieldDescription
classificationThe requestedReasoner, the reasoner actually used, implementation, consistent, unsatisfiableClasses, and elapsedMillis. The reasoner used can differ from the one requested.
profileThe OWL 2 profile: name, supported, and profiles
countsCounts of documents, axioms, imports, diagnostics, and unsatisfiable classes
axiomsThe 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.
importsThe imports: iri, document, status, message, blocking, depth, and resolvedDocument
diagnosticsThe parse and classification messages: severity, code, document, message, and blocking
limitsThe 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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
413Payload Too Large. A document or the whole request is over the size limit.
422Unprocessable Entity. The documents parse, but use constructs the reasoner doesn't support.
503Service Unavailable. No classification capacity is free. Try again later.
504Gateway 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​

ParameterTypeDescriptionRequired
nsfilterStringNamespace 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​

ParameterTypeDescriptionRequired
contractVersionNumberThe contract version. Must be 1.Required
axiomIdStringAn axiom id from the Preview OWL documents responseRequired
previewObjectThe full request body you sent to Preview OWL documentsRequired

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​

FieldDescription
axiomIdThe axiom ID you sent
availableWhether an explanation was found
reasonWhy no explanation is available, when available is false
reasonerThe reasoner used
implementationThe reasoner implementation
supportingAxiomIdsThe 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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
413Payload Too Large. A document or the whole request is over the size limit.
422Unprocessable Entity. The documents parse, but use constructs the reasoner doesn't support.
503Service Unavailable. No classification capacity is free. Try again later.
504Gateway Timeout. Classification took longer than its time limit.