Ontology — approved how-to

The ontology catalog (Knowledge Explorer stack) is a separate surface from Console Explore. On screen it is labelled Ontology Explorer. This guide covers how SiS uses the catalog: load the contract (sis-core + shapes), validate SHACL, query SPARQL.

This does not replace Explore and is not a full product manual for the upstream explorer. Other workspaces (Vocabulary, Reasoning, Decisions, Import/Merge, Registry, Entity resolution, Lineage, KG overview) exist — open them when you need them.

1. Open

Two paths, the same place:

1. Dedicated ontology host on your domain (e.g. onto.example.org).
2. Ontology button in the Console (left of Explore) — a shortcut. Visible only with dev:write.

New tab → OIDC sign-in → the email must be on the allow list (SOCIETY_ADMIN_EMAILS).

If the button is disabled: the public ontology URL setting is missing from the bundle .env and the compose file on the server. The hover title states the reason.

The explorer SPA calls /api/… at the site root. Serving it under a Console subpath yields a blank tab with HTTP 200.

Local Development: 127.0.0.1:8000 + graph store :6379. Pin Python 3.12 in the image (3.14 breaks gensim). On localhost the SPA may run without API key (anonymous-access flag enabled). On a client installation: fail closed.

2. What to load

The artifacts live in the SiS repo, not inside the explorer image:

File	Job
ontology/sis-core.jsonld	Society Graph ontology. Namespace https://w3id.org/sis/ns#. ~45 classes, ~50 object properties.
ontology/sis-shapes.ttl	SHACL shapes (domain, range, cardinality, closed vocabulary).

In the explorer: Ontology hub → load / import those two files (JSON-LD and Turtle). Do not expect deploy to leave them already inside: the client graph is deployed empty on purpose.

Trap when parsing sis-core.jsonld. A flat RDF Graph may see only the document header (~25 triples). Nodes live in a named graph (@id + @graph). Use a Dataset for hundreds of triples. tools/check_shacl.py uses the correct path; a flat import in the workbench may validate nothing.

3. Minimum tour (what matters to SiS)

Workspace	What it is for in SiS
Ontology hub	Load sis-core / shapes; see contract classes and properties
SHACL (hub tab)	Validate the graph against sis-shapes.ttl
SPARQL (Analyze)	Query the already materialized catalog
Graph (Explore)	See the catalog graph — not Console Explore

Validate SHACL — inference=none

rdfs:range is not a constraint: it is an entailment rule. With inference=rdfs, any sh:class on that property is tautological.

SiS shapes validate with inference=none (written in sis-shapes.ttl and tools/check_shacl.py). If the workbench offers an RDFS inference toggle, leave it off for these shapes.

4. What it does not do

• It is not Explore. The live graph is recomputed from SQL; this looks at an already materialized catalog.
• It does not replace the Society Graph.
• There is no automatic SiS → catalog sync today.
• There is no tenancy inside the engine: one store, one graph per installation.
• MCP to agents is not in the agents-host image by default.

5. Deploy

Edge proxy → OIDC gate → relay → explorer. API key is injected behind the gate.

Service deployment: Deploy ontology.