> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Build your first ontology

> Model a retail company in Ontology Studio, publish release 1.0.0, and see the exact context an agent gets, in about 15 minutes.

<Badge color="orange">Preview</Badge>

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:

```mermaid theme={null}
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER }o--o{ PRODUCT : contains
  STORE
```

| 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](/registry/apps/how-tos/install-apps).
* You can create in at least one workspace.
* Open Ontology Studio: in **Brain**, select **Apps**, then select **Ontology**. See [Find your installed apps](/registry/apps/how-tos/find-installed-apps).

<Steps>
  <Step title="Create the ontology">
    1. On **All ontologies**, choose **New ontology**.
    2. Select the **Workspace** and enter `Retail` as the **Name**. Studio fills in the **API name** `retail`.
    3. 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**.
    4. 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.
  </Step>

  <Step title="Add the four object types">
    1. Under **Model**, open **Definitions** and choose **New definition**.
    2. Select the **Object type** kind, enter `Customer` as the **Name**, and keep **Object kind** on **Entity · something that exists over time**.
    3. Choose **Create draft**.
    4. 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.
  </Step>

  <Step title="Add properties">
    1. Open **Customer** and select the **Properties** tab.
    2. Choose **Add property**. Enter the **API name** `customer_id`, choose the **Data type** **Text**, and turn on **Required** and **Identifier**. Choose **Add property**.
    3. Add `status` as **Text**. Optionally add **Allowed values** such as `active` and `churned`.
    4. Choose **Save draft**, or press ⌘S or Ctrl+S.
    5. Repeat for the other types, using the properties in [What you'll build](#what-youll-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.
  </Step>

  <Step title="Connect the types with links">
    1. In **Definitions**, choose **New definition** and select the **Link** kind.
    2. 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".
    3. Create `contains` from **Order** to **Product** with the reverse name `contained_in`.
    4. 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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Publish release 1.0.0">
    1. Under **Version**, keep the suggested **Version number** `1.0.0`.
    2. 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`.
  </Step>

  <Step title="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.

    1. Keep the scope on **Logical model**.
    2. 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:

    ```json theme={null}
    {
      "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."
    }
    ```
  </Step>
</Steps>

## 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](/ontology/concepts/bindings): map Customer, Order and Product to your warehouse tables.
* [Use Ontology with agents](/ontology/how-tos/use-with-agents): connect an MCP client and pick the right tool.
* [Ontology concepts](/ontology/concepts): interfaces, shared properties, actions and terminology.
* [Publish an ontology through the API](/cookbooks/how-tos/ontology): automate the same steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.