Build an ontology

This guide walks you through building an Ontology — the typed world model that defines what exists in your project and how the pieces relate. By the end you will have entity types, link types, properties, and constraints, and you will have watched the workspace reconfigure itself around them. You need an empty or near-empty project; you can build the ontology by hand, with Jax, or both.

The ontology is the source of truth for structure. Everything downstream — toolbar, side panels, map layers, validators, and the Skills you load — derives from it. Get the types right and the rest of the app follows.

Steps

1. Define your entity types first. An entity type is a kind of thing that exists in your world — a valve, a transformer, a waypoint, a parcel. Name them before anything else, because links and constraints reference them. Describe the domain to Jax and let it draft the set.

Draft an ontology for a water distribution network: valves, pipes, pumps, reservoirs, and service connections. Keep it minimal.

1. Add properties to each type. Properties are the fields an entity carries — diameter, pressure rating, install date, status. Give each a type and, where it helps, an allowed-value set and a default.

Add a diameter_mm number and a material field to pipes, allowed values steel, ductile-iron, pvc, default pvc.

1. Define link types between entities. A link type captures a relationship — a pipe connects two valves, a service connection belongs to a pipe. Links are what make the model a graph instead of a list.

Connect pipes to valves with a terminates_at link, and service connections to pipes with a served_by link.

1. Add constraints. Constraints are first-class rules the validator enforces and Jax respects on every run. Add the ones that define a valid design in your domain.

Add a constraint: every service connection must be within 300 m of the pipe that serves it.

1. Watch the app reconfigure. As you save, the workspace rebuilds around the ontology — new entity types appear as toolbar tools and map layers, properties show up in side panels, and constraints start surfacing violations on the Globe. There is no separate build step; the ontology drives the UI directly.

1. Iterate with Jax as edge cases appear. Real domains reveal gaps. Add fields and rules as you discover them, and ask Jax what each change migrates.

Add a criticality field to valves with values low, medium, high. What does this migrate for existing valves?

Tips

• Start minimal. A handful of entity types you understand beats a sprawling model you do not. You can always extend.
• Model shared concepts once. A road or a building used by several domains should be a single entity type, not one per domain.
• Keep names domain-true and consistent — Jax reads them, and clear names make its reasoning clearer too.
• The ontology is immutable per project by design; layer changing behavior on top with Skills rather than reshaping the types mid-flight.

Where to go next

• Add behavior on top of your types in Work with skills.
• Bring real data into your types with Connect a data source.
• Read the conceptual model in Ontology.