This is a partial user and operations guide. The full guide is available to platform subscribers and active users only. We publish this public selection so evaluators get an initial sense of capabilities and workflows. Private guide content may change with ongoing product improvements.
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:
- Dedicated ontology host on your domain (e.g.
onto.example.org). - 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. tools/ops/cargar-ontology-catalog.py loads the flattened ontology and an example graph through the API; the explorer keeps its graph in memory, so it is empty again after every restart, and the ontology-catalog-cargador service refills it on its own once deployed.
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-hostimage by default.
5. Deploy
Edge proxy → OIDC gate → relay → explorer. API key is injected behind the gate.
Service deployment: .