Getting Started

Semantic domains can be built through the UI or by writing YAML/JSON templates directly. This guide walks you through building a complete domain template from scratch, one concept at a time.

When to use template editing:

• Bulk configuration of many fields or datasets
• Version-controlled domains stored in Git
• CI/CD pipelines that deploy domain changes automatically
• Copying configurations between environments
• AI agents or scripts generating domains programmatically

How to open the template:

1. Open your domain in the Domain Editor
2. Click the Template tab
3. Toggle between YAML and JSON format
4. Edit the template and click Save

Minimal Template

The smallest valid domain template:

schemaVersion: "2.1"
datasets: []

All other top-level fields are optional and default to empty. The full skeleton:

schemaVersion: "2.1"
aiContext: "Fiscal years start in February."  # Context for agents (optional)
datasets: []             # Datasets with identifiers, facts, and dimensions
relationships: []        # How datasets join
metrics: []              # Every metric: dataset metrics and composed metrics
composedDimensions: []   # Domain-level row expressions over inputs
grainMappings: []        # Columns a composed dimension uses in other datasets

A template has four building blocks:

• Facts and dimensions live on a dataset. Both work row by row. A fact is a quantity you aggregate (like amount); a dimension is an attribute you group and filter by (like region).
• Metrics aggregate rows. A dataset metric aggregates one dataset (SUM(amount) on orders). A composed metric combines named inputs, often from several datasets (net revenue from orders and returns).
• Relationships join datasets. from is the many side; to is the side whose fields identify one row.
• Context (aiContext) tells agents and natural-language questions how to read any of the above.

Guide Sections