Build your first ontology

Preview In this tutorial you model a small retail company in Ontology Studio, publish it as release 1.0.0, and ask the release a question the way an agent would. You don’t need any SQL or warehouse access. Time: about 15 minutes.

What you’ll build

A retail ontology with four object types and two links:

Object type	Object kind	Properties
Customer	Entity	`customer_id` (identifier), `status`
Order	Event	`order_id` (identifier), `ordered_at`
Product	Entity	`sku` (identifier), `category`
Store	Entity	`store_id` (identifier), `city`

Link	From → To	Relationship	Reverse name
`places`	Customer → Order	One to many	`placed_by`
`contains`	Order → Product	Many to many	`contained_in`

Before you begin

An administrator has installed the Ontology app. See Install and manage apps.
You can create in at least one workspace.
Open Ontology Studio: in Brain, select Apps, then select Ontology. See Find your installed apps.

Create the ontology

On All ontologies, choose New ontology.
Select the Workspace and enter Retail as the Name. Studio fills in the API name retail.
Optionally open More options and set an IRI namespace such as https://example.com/retail#. Studio then suggests an IRI for each definition. Leave the Versioning policy on Backward compatible.
Choose Create ontology.

Studio opens the ontology’s Overview, with a Get to 1.0.0 checklist: add object types, connect them with links, fix the issues, and publish.

Add the four object types

Under Model, open Definitions and choose New definition.
Select the Object type kind, enter Customer as the Name, and keep Object kind on Entity · something that exists over time.
Choose Create draft.
Repeat for Product and Store as entities, and for Order with Event · something that happened.

Definitions now lists four object types, each marked as a draft.

Add properties

Open Customer and select the Properties tab.
Choose Add property. Enter the API name customer_id, choose the Data type Text, and turn on Required and Identifier. Choose Add property.
Add status as Text. Optionally add Allowed values such as active and churned.
Choose Save draft, or press ⌘S or Ctrl+S.
Repeat for the other types, using the properties in What you’ll build. Use Date and time for ordered_at.

An identifier must be required and a single value. If you forget Required, Studio shows An identifier must be required before you can save.

Connect the types with links

In Definitions, choose New definition and select the Link kind.
Enter places as the Name, choose Customer under From and Order under To, and set the Reverse name to placed_by. Choose Create draft. A new link starts as One to many, which is what places needs. The link page reads “A Customer has many Orders · an Order has exactly one Customer”.
Create contains from Order to Product with the reverse name contained_in.
On the contains page, set Relationship to Many to many and choose Save draft.

Open Graph to check the shape: object types are cards, and each link is a line labelled with its name, with line ends that show how many take part. Store has no links yet, which is fine.

Validate and review

Under Release, open Publish. Studio checks every draft together as soon as the page opens.

Issues shows errors and warnings. A link or type without an IRI gets a warning, because RDF, OWL and SPARQL tools can’t address it. Warnings don’t block publishing.
Fix any errors. Each issue links to the definition it names.

When the drafts are clean, the page shows All checks passed, with the number of definitions and warnings. Because this is the first release, there are no changes to compare.

Publish release 1.0.0

Under Version, keep the suggested Version number 1.0.0.
Choose Publish 1.0.0.

Studio shows Release 1.0.0 published and its Release ID, which starts with rel_. Choose Copy release ID and keep it for the last step. The release can’t change: to fix something later, publish 1.0.1 or 1.1.0.

See the context an agent gets

Under What’s next, choose Ask this release. Studio opens Agent context on the Ask tab with release 1.0.0 selected.

Keep the scope on Logical model.
Enter the Question customers and their orders and choose Ask.

The results are the definitions an agent would receive. Customer and Order are marked matches your words, and the places link can appear as linked to a match. The header shows a token estimate such as ≈ 900 of 12,000 tokens and fits, which means nothing was cut.An agent gets the same result by calling the extension__ontology__get_context MCP tool. The ontology ID is the part of the Studio address after #/o/. Open a session with mcp__initialise first, then replace the example IDs and session_id with your values:

{
  "ontology_id": "ontology_01example",
  "release_id": "rel_01example",
  "query": "customers and their orders",
  "max_resources": 15,
  "max_depth": 2,
  "max_tokens": 12000,
  "session_id": "mcp_session_<your-session-id>",
  "rationale": "Read the released retail definitions for customers and orders."
}

Verify

Releases lists 1.0.0 with its date, author, definition count and checksum.
The toolbar status shows Live 1.0.0.
The Data bindings, Knowledge records and Agent context pages now appear in the navigation. They only appear once a release exists.

What you accomplished

You built a six-definition model, validated it as one graph, and published an unchangeable release. You then saw the bounded slice an agent receives for a question, with the release ID and token estimate that prove which model it read.

Next steps

Bindings: map Customer, Order and Product to your warehouse tables.
Use Ontology with agents: connect an MCP client and pick the right tool.
Ontology concepts: interfaces, shared properties, actions and terminology.
Publish an ontology through the API: automate the same steps.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

What you’ll build

Before you begin

Verify

What you accomplished

Next steps

​What you’ll build

​Before you begin

​Verify

​What you accomplished

​Next steps

What you’ll build

Before you begin

Verify

What you accomplished

Next steps