Client reference

The Ontoshire client validates your instance data (ABox) against a pinned ontology, its author SHACL shapes, and its dependency closure. The engine is pySHACL; it runs in your environment and your data never leaves it.

New here? Follow the Quickstart first, then use this page as the reference.

Install#

pip install ontogate            # CLI + Python SDK — installs the `ontogate` command
pip install "ontogate[aws]"     # + AWS SigV4 signing for Amazon Neptune

Requires Python 3.10+. Authenticate once with a token before pulling any schema.

The validate command#

Point --schema at a pinned owner/repo@version and --data at your instance file:

ontogate validate --schema acme/health@v1.2.0 --data ./patients.ttl

--data accepts any RDF file Ontoshire’s parser understands — Turtle, N-Triples, RDF/XML, JSON-LD, TriG, N3 — inferred from the extension.

All flags#

Exit codes#

The command is built for CI — the exit code is the contract:

Report formats#

text (default) — human-readable, one line per violation with focus node, path, constraint, and message.

json — a stable, flattened report. Every verdict carries the run metadata (schema, mode, context depth, inference) so the bound it was computed under travels inside the report:

{
  "conforms": false,
  "schema": "acme/health@v1.2.0",
  "mode": "contextual",
  "contextDepth": 1,
  "inference": "none",
  "results": [
    {
      "focusNode": "http://ex.org/patient/42",
      "resultPath": "http://ex.org/mrn",
      "sourceConstraintComponent": "MinCountConstraintComponent",
      "severity": "Violation",
      "message": "A Patient must have exactly one medical record number.",
      "value": null
    }
  ]
}

jsonld — the raw sh:ValidationReport as JSON-LD, for RDF-native pipelines that want to store or query the report itself.

Validation modes#

Self-contained (default)#

Your payload is validated as a closed graph against the shapes + the ontology’s definitions. This is the right mode when the data you’re checking is complete on its own — a file about to be imported, a generated dataset, a CI fixture.

Contextual#

Pass --target-endpoint when your shapes reach into data that already lives in a triple store — a node your payload references but doesn’t include. The client fetches the bounded context it needs and validates payload ∪ context:

ontogate validate --schema acme/health@v1.2.0 --data ./new-encounters.ttl \
  --target-endpoint https://graph.internal/repositories/prod \
  --context-depth 1

Only violations on your payload’s own nodes are reported — data already in the store is treated as valid ground truth, not re-judged. --context-depth bounds how many hops of references are pulled (default 1). If the fetch fails, the command errors (exit 2) rather than silently falling back to a self-contained pass — a false pass is worse than no answer.

Endpoint authentication#

Target-store credentials are resolved locally and never sent to Ontoshire.

• --target-auth basic — reads ONTOGATE_TARGET_USERNAME / ONTOGATE_TARGET_PASSWORD from the environment.
• --target-auth sigv4 --aws-region eu-west-1 — AWS SigV4 for Amazon Neptune with IAM auth. Uses the default AWS credential chain; needs pip install 'ontoshire[aws]'.

In CI#

Create a token in Settings → API Tokens, store it as the ONTOGATE_API_TOKEN secret, and gate your pipeline on the exit code:

- name: Validate against Ontoshire
  run: |
    pip install ontogate
    ontogate validate --schema acme/health@v1.2.0 --data ./data.ttl
  env:
    ONTOGATE_API_TOKEN: ${{ secrets.ONTOGATE_API_TOKEN }}

Python SDK#

The same engine is importable for embedding validation in your own pipelines:

from ontoshire import OntogateClient

client = OntogateClient(token="ons_…")   # or omit → env / stored credentials
report = client.validate("acme/health@v1.2.0", "./patients.ttl")

print(report.conforms)          # bool
for v in report.results:
    print(v.focus_node, v.message)

Troubleshooting#