# askwol

askwol reviews OWL ontologies for modelling issues and publishing practices.

- [Online tool](https://lod-4tu.tudelft.nl/askwol/)
- [OpenAPI schema](https://lod-4tu.tudelft.nl/askwol/openapi.json): request and response contracts.
- [API documentation](https://lod-4tu.tudelft.nl/askwol/docs): interactive examples and check descriptions.
- [Publishing guide](https://lod-4tu.tudelft.nl/askwol/guide): explanations and remedies.
- [Source code](https://github.com/TDCC-NES/askwol): MIT licence.

## API

POST https://lod-4tu.tudelft.nl/askwol/api/validate with a multipart `file` field.

POST https://lod-4tu.tudelft.nl/askwol/api/validate/content with a JSON object:

- `format`: `json-ld`, `turtle`, `xml` (RDF/XML), `nt`, or `n3`.
- `content`: RDF text; JSON-LD also accepts an object or array directly.
- `base_uri`: optional absolute IRI for resolving relative IRIs.

Both endpoints return a full JSON report by default. Add `?compact=true` for findings, counts, check coverage, and reasoning scope without term inventories. The size limit is 20 MB; for the content endpoint it applies to the complete JSON request.

```bash
curl --request POST \
  'https://lod-4tu.tudelft.nl/askwol/api/validate/content?compact=true' \
  --header 'Content-Type: application/json' \
  --data '{"format":"json-ld","content":{"@context":{"owl":"http://www.w3.org/2002/07/owl#"},"@id":"https://example.org/ontology","@type":"owl:Ontology"}}'
```

HTTP 200 means processing completed; inspect `severity_summary.has_errors` to determine whether errors were found. HTTP 422 returns either a report with RDF parse errors or a `detail` list for an invalid request. Other errors return a `detail` string: 400 malformed multipart, 413 size limit, 415 unsupported content type, 429 rate limit, 500 worker failure, 503 busy service, or 504 timeout.

## Reading results

Use `severity_summary.findings`; each finding has a stable `rule`, its `check`, `severity`, and optional `subject`, `message`, and `guide_url`. Group findings by severity: `error`, `warning`, or `recommendation`. Counts refer to individual findings.

The full report's per-item `status` values (`ok`, `warn`, `fail`, `skip`) describe check outcomes, not finding severity. The compact report's `checks` list describes coverage (`completed`, `partial`, `skipped`, `unavailable`). Do not treat skipped or unavailable checks as passed.

Reasoning covers selected OWL RL/RDF checks in the current document; imports are excluded. `reasoner.consistent: null` means consistency has not been established. Datatype checks do not validate literal values. Remote term-definition checks cover external subject IRIs, excluding predicate-only and object-only references. A report without errors does not establish full OWL consistency, profile conformance, or suitability for a domain.

## CLI

Install with `pipx install askwol` (Python 3.10+), then run:

```bash
askwol check ontology.ttl --format json
```

Exit codes: 0 means no errors (warnings or recommendations may remain); 1 means errors were found; 2 means an invalid CLI invocation. The CLI returns the full report.
