Overview
Give business records a shared meaning, connect their evidence and publish reusable reads
An ontology defines the things your project talks about—orders, customers, deliveries—and the properties and relationships that describe them. Semogram uses that model to read records across systems, persist mapped facts where needed, retain reviewable assertions and answer queries with execution evidence.
Creating an Order class does not create orders. A definition describes what an Order means; a binding tells a read where Order data comes from; a materialization run stores mapped records; a query selects the values a caller wants.
Five layers with different jobs
| Layer | What it owns | Concrete example |
|---|---|---|
| Definition | Classes, properties, relationships and shapes in versioned model files | Order has a string order ID, decimal total and a relationship to Customer |
| Read binding | A term's source, read method, resolution and access policy | Order status comes from the status column of a Postgres endpoint |
| Materialized fact | An entity, property, relationship or source identity stored through a fact-store capability | Order https://example.com/orders/1 has total 120 |
| Assertion | A reviewable statement, value, evidence and lifecycle | A delivery receipt supports “Order 1 was delivered” |
| Published query | A released input/output contract over resolved bindings | Return order IDs, totals and reviewed delivery status |
An assertion can inform an ontology query through an asserted binding. It does not become an ordinary database column or overwrite materialized facts simply because someone approves it.
What belongs to a project
Definitions, compiled project packages, read bindings and queries belong to a project. Plugin installations and data endpoints belong to the workspace. Different projects may select the same workspace endpoint while using different models, bindings and queries. Assertion records carry workspace scope and, in the project workflows described here, project scope.
A definition asset has its own saved versions. Compilation combines active project definitions into a queryable package. The compiled package UUID and numeric package version differ from the definition asset UUID and its saved-version UUID. Keep these identities separate when configuring bindings, mappings and queries.
Choose how each term is read
| Read method | Data source | When to use it |
|---|---|---|
| Virtual | A readable endpoint, evaluated at read time | Keep operational records in their existing system |
| Materialized | An ontology fact store populated by a pipeline | Persist mapped entities, relationships and source identities |
| Asserted | Project assertion records selected by status and evidence policy | Use reviewed claims without silently discarding disagreement |
| Inferred | A supported CEL expression over other bound terms | Compute an output such as isOpen from the bound status |
These methods can be combined in one query using a shared entity identity. A root class establishes which entities are being read; output terms may use other methods. Inferred outputs do not manufacture a new root population. Query-time ontology entailment is a separate, explicitly enabled named-term relation profile.
Start with one question
Your first model and query walks through a complete two-order fixture: model files, a Postgres source, read bindings, query definition, publication and verification. No prior tutorial is required.
Then use the topic that matches your task:
| Task | Read next |
|---|---|
| Define entities, relationships and constraints | Define the model |
| Connect terms to live or stored data | Read bindings |
| Store entities and relationships | Materialize facts |
| Record and review a claim | Assertions |
| Publish a reusable question | Query authoring |
| Understand result evidence and limitations | Execute and inspect |
| Change a model safely | Definition versions |
What the graph proves
The project graph shows model structure from definitions. A displayed Customer node proves the class is in the model; it does not prove customer records were read or that a materialization run succeeded. Inspect source samples, run outputs, persisted facts and query results separately.
A successful query is also not automatically exhaustive or current. Inspect completeness, consistency, source snapshots, diagnostics, release and binding identities before relying on its answer. A published query stabilizes the released logic; source data can still change.