# Domains

Each domain is the README.md of a directory under domains/. A small YAML frontmatter block carries its name and description; the Markdown body carries the business context.

The root domain is `domains/README.md`; every other domain is `domains/<path>/README.md`. Domain documents follow the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf), so they read as plain documentation on GitHub and in any Markdown editor.

## The parts

| Part | Where | Notes |
| --- | --- | --- |
| `type` | frontmatter, required | Always `Domain`. It is what marks the README as a domain file; a README without it is treated as ordinary prose and ignored |
| `title` | frontmatter | Human name, shown in the UI and to the agent. Always set it |
| `description` | frontmatter | One or two sentences. Shown when the parent domain lists its children |
| body | markdown | Everything after the frontmatter: the domain’s prose context. This is where business rules, glossary, and gotchas go |

**Frontmatter follows the same strict rules as the YAML fields.** Only `type`, `title`, and `description` are recognized. An unknown key, a typo like `titel`, is reported as drift and fails the check rather than being silently kept.

## Example

```markdown title="cassis/domains/seller_acquisition/README.md"
---
type: Domain
title: Seller acquisition
description: 'Marketing qualified leads and closed deals: how Stallora wins new sellers.
  Bridges to marketplace sellers.'
---

Prospective sellers enter as marketing qualified leads; the sales team closes
some of them into deals; a closed deal creates a seller on the marketplace.

<!-- cassis:nav:begin (generated, do not edit) -->
<!-- cassis:nav:end -->
```

## Generated navigation

Below the body, Cassis maintains a generated block between `cassis:nav:begin` and `cassis:nav:end` markers linking the tables and metrics placed in the domain, so the README browses on GitHub. It is regenerated on every format and publish, so do not hand-edit it. If it goes stale, because you placed or moved a table without re-running the formatter, the check fails and points you at [`cassis ontology fmt`](/reference/cli/ontology/).

## The directory path is the domain path

A domain’s path is its directory path under `domains/`. It is not stored anywhere inside the file, and the file is always named `README.md`.

| Domain path | File |
| --- | --- |
| (root) | `domains/README.md` |
| `marketplace` | `domains/marketplace/README.md` |
| `marketplace/measuring-sales` | `domains/marketplace/measuring-sales/README.md` |

-   **Moving or renaming a directory renames the domain.** Tables and metrics reference domains by path (`domain_path: marketplace`), so update those references in the same pull request.
-   Path segments are lowercase slugs: letters, digits, `_`, `-`. No spaces, no uppercase.
-   Give **every level** its own `README.md`, intermediate ones included. A child directory without a parent domain file leaves the parent unnavigable.

## The root domain is the global context

`domains/README.md` supplies the agent’s global business context for every question, so it is where project-wide rules belong: what a win is, which rows to exclude by default, which vocabulary maps to which concept. A rule written here applies everywhere; a rule written in a leaf domain applies only when that domain is in play.

**Migrating from the old format.** Repositories authored before this used YAML domain files, `_project.yml` for the root and `domains/<path>/_domain.yml` for the rest. Cassis still reads them, so nothing breaks on upgrade. Convert whenever you like with `cassis ontology fmt` (cassis-cli 1.1.0 or newer), which rewrites the domain files and leaves the diff for you to review.