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

# The domain definition

> The JSON shape of a domain — its domain object, variables, and activities — as exported, imported, and authored. The complete structure of a TrueMath domain.

A [domain](/concepts/domains) has a single, portable representation: a JSON **definition** holding the domain's labels, its [variables](/concepts/variables), and its [activities](/concepts/activities). This is the form a domain takes when you [export, import, or copy](/authoring/creating-a-domain#managing-a-domain) it, and it is the complete shape of everything a domain is made of. This page is the reference for that structure — every field, its type, and its allowed values.

If you are authoring by hand you rarely write this JSON directly; you build the domain up from [activities](/authoring/writing-activities), [equations](/authoring/writing-equations), and [variables](/authoring/defining-variables), and TrueMath holds the definition for you. The structure here is what those pieces add up to, and what you produce when you generate a domain programmatically.

<Note>
  This is the **definition** shape — what a domain *is*. It is related to, but not the same as, the read shapes the API returns from [`GET /v1/domains/:id/activities`](/api/domains): the definition relates activities to variables by **key**, while the read endpoints relate them by `variable_id` and add server-side fields such as identity, version, and activity state. Use this page for the portable definition; use [Domains (API)](/api/domains) for what a calculation or read endpoint returns.
</Note>

## Top-level structure

A definition is an object with three members:

```json theme={null}
{
  "domain":    { "title": "...", "description": "..." },
  "variables": [ /* one entry per variable */ ],
  "activities": [ /* one entry per activity */ ]
}
```

| Member       | Type   | Description                                                                           |
| ------------ | ------ | ------------------------------------------------------------------------------------- |
| `domain`     | object | The domain's details — see [The domain object](#the-domain-object).                   |
| `variables`  | array  | Every [variable](/concepts/variables) in the domain — see [Variables](#variables).    |
| `activities` | array  | Every [activity](/concepts/activities) in the domain — see [Activities](#activities). |

Variables and activities relate to one another **by key**, not by position or by id — see [How variables and activities relate](#how-variables-and-activities-relate).

<Note>
  **What an author assigns, and what TrueMath assigns.** A variable's `key` is the only identifier you choose — the human-readable name you write in [equations](/authoring/writing-equations) and input (`loan_amount`, `interest_rate`). Everything else is assigned by TrueMath, not author-chosen: every `id` (a UUID), each activity `key` (`act_` followed by hex), and the domain's key (`dm_` followed by hex). All are stable for the life of the domain.
</Note>

<Tip>
  **Generating a new domain.** Omit every system-assigned identifier: leave out each `id` and each activity `key`, and give the `domain` object only a `title` and `description`. Supply just the author content — variable `key`s, labels, `default_value`s, and display configuration, plus each activity's `equation` and `calculable` list. TrueMath assigns the identifiers on import. The `id` and activity `key` fields shown throughout this page appear in a definition *exported* from an existing domain, where TrueMath has already assigned them.
</Tip>

## The domain object

```json theme={null}
"domain": {
  "title": "Mortgage",
  "description": "Mortgage and home-loan calculations: home price, down payment, loan amount, interest rate, monthly payment, amortization, escrow, and related figures."
}
```

| Field         | Type   | Description                                                                                                                                                                    |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`       | string | The domain's human- and agent-readable name.                                                                                                                                   |
| `description` | string | What the domain is for. Clear, precise descriptions improve natural-language and agent results, so write it precisely — see [Creating a domain](/authoring/creating-a-domain). |

The definition carries no identifier in the `domain` object — only its title and description. A domain's identity is assigned and managed by TrueMath and does not travel inside the definition body. Importing a definition applies it to the domain you import it into, overriding that domain's current contents; see [Managing a domain](/authoring/creating-a-domain#managing-a-domain).

## Variables

Each entry in `variables` describes one [variable](/concepts/variables): its key, its labels, its default, and how it is displayed.

```json theme={null}
{
  "id": "53c87c9b-6dfb-4869-9eea-4f71560f282d",
  "key": "apr",
  "title": "Annual Percentage Rate (APR)",
  "description": "Annual percentage rate displayed as a percentage...",
  "prompt": "",
  "default_value": "",
  "display_type": "percent",
  "display_metadata": {
    "number": { "decimal_format": "decimals_3" }
  }
}
```

| Field              | Type   | Description                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | UUID   | System-assigned identifier for the variable.                                                                                                                                                                                                                                                                                            |
| `key`              | string | The variable's [key](/authoring/defining-variables#key-and-labels) — the **author-chosen** name used in equations and input. Lowercase, starts with a letter, contains letters, digits, and underscores, unique within the domain.                                                                                                      |
| `title`            | string | Human- and agent-readable label.                                                                                                                                                                                                                                                                                                        |
| `description`      | string | What the variable means. Clear, specific descriptions improve natural-language and agent results — see [Defining variables](/authoring/defining-variables#key-and-labels).                                                                                                                                                              |
| `prompt`           | string | Optional, authoring-only [interpretation guidance](/authoring/defining-variables#llm-prompt) for natural-language input onto this variable. An empty string `""` when unset. It round-trips through export, import, and copy, but is never present in a calculation result or any [public API](/api/domains), sharing, or MCP response. |
| `default_value`    | string | The [default](/authoring/defining-variables#default-value-and-unit) applied when a calculation provides none, written as a combined `"value unit"` string (`"30 yr"`, `"0 USD"`, `"0.20"`), or an empty string `""` when the variable has no default.                                                                                   |
| `display_type`     | string | How the value is interpreted and shown — one of the [display types](#display-types) below.                                                                                                                                                                                                                                              |
| `display_metadata` | object | The display configuration, keyed by the variable's structural type — see [display\_metadata](#display-metadata).                                                                                                                                                                                                                        |

### Display types

`display_type` is one of:

| Value          | Meaning                                                                                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number`       | A plain number, shown with thousands separators and the [unit](/concepts/units-and-precision) its value carries, if any. A monetary amount is a `number` whose unit is a currency. |
| `percent`      | A rate shown as a percentage. A unit on the value is still shown — `0.20 ft` displays as `20% ft` — though pairing a unit with a percentage is unusual.                            |
| `no_separator` | A number shown without thousands separators, such as a year, with the unit its value carries, if any.                                                                              |
| `table`        | A collection of values in rows and columns — see [Tables](/authoring/tables).                                                                                                      |
| `bar_chart`    | A table presented as a bar chart — see [Charts](/authoring/charts).                                                                                                                |
| `pie_chart`    | A table presented as a pie chart — see [Charts](/authoring/charts).                                                                                                                |

### display\_metadata

`display_metadata` holds the variable's display configuration under a **single key naming its structural type**. The three scalar display types — `number`, `percent`, and `no_separator` — all nest under `number`; the others nest under `table`, `bar_chart`, or `pie_chart`.

#### Scalar variables — `number`

For `number`, `percent`, and `no_separator`:

```json theme={null}
"display_metadata": {
  "number": { "decimal_format": "decimals_2" }
}
```

| Field            | Type   | Description                                                                                                                                                                                                                                                                                      |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `decimal_format` | string | The precision applied when the value is shown: `decimals_0` through `decimals_9` for a fixed number of decimal places, or `decimals_float` for the value's natural precision (at most 10 decimal places). Display only — the stored value keeps [full precision](/concepts/units-and-precision). |

#### Table variables — `table`

```json theme={null}
"display_metadata": {
  "table": {
    "start_row_index": 1,
    "columns": [
      { "name": "Payment",        "display_type": "number", "decimal_format": "decimals_2" },
      { "name": "Principal Paid", "display_type": "number", "decimal_format": "decimals_2" },
      { "name": "Interest Paid",  "display_type": "number", "decimal_format": "decimals_2" },
      { "name": "Ending Balance", "display_type": "number", "decimal_format": "decimals_2" }
    ],
    "rows": { "names": [] }
  }
}
```

| Field             | Type    | Description                                                                                                                                                                                                                                                                                                               |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start_row_index` | integer | The number shown as the label of the first row — a display indicator like a spreadsheet's row numbers, not the table's intrinsic indexing (which is always 1-based in equations). Usually `1`; sometimes `0`, e.g. a cash-flow table whose initial flow is period 0. See [Tables](/authoring/tables#configuring-columns). |
| `columns`         | array   | The table's columns. **Columns are defined; rows are data** — see [Tables](/authoring/tables#rows-versus-columns). Each column is an object with `name` (string), `display_type` (a scalar type: `number`, `percent`, or `no_separator`), and `decimal_format`.                                                           |
| `rows`            | object  | `rows.names` is an array of [row labels](/authoring/tables#row-labels), or an empty array `[]` when the table has no row labels.                                                                                                                                                                                          |

Columns carry no unit field: each cell carries its own unit with its value — see [Tables as a stored value](/math/types/tables#as-a-stored-value).

#### Bar chart variables — `bar_chart`

A chart is a [presentation of a table](/authoring/charts); the variable's value stays a table and `display_metadata.bar_chart` configures how it is drawn.

```json theme={null}
"display_metadata": {
  "bar_chart": {
    "series_by": "rows",
    "stacked": false,
    "x_axis": { "title": "Periods" },
    "labels": { "source": "index", "start_series_index": 1 },
    "series": [
      { "name": "Ending Balance", "display_type": "number", "decimal_format": "decimals_2" }
    ]
  }
}
```

| Field       | Type    | Description                                                                                                                                                                      |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `series_by` | string  | Whether each series is a `row` or a `column` of the underlying table — `"rows"` or `"columns"`.                                                                                  |
| `stacked`   | boolean | Whether series are stacked into one bar per group (`true`) or drawn side by side (`false`).                                                                                      |
| `x_axis`    | object  | `x_axis.title` is the axis label.                                                                                                                                                |
| `labels`    | object  | Where bar labels come from. `source` is `"index"` (the row index) or `"first_series"` (the table's first series). `start_series_index` is the series index labeling starts from. |
| `series`    | array   | One entry per plotted series, each with `name`, `display_type`, and `decimal_format` — the same scalar formatting a [column](#table-variables-table) uses.                       |

#### Pie chart variables — `pie_chart`

```json theme={null}
"display_metadata": {
  "pie_chart": {
    "display_type": "number",
    "decimal_format": "decimals_2",
    "slices": {
      "names": ["Payment", "Private Mortgage Insurance", "Property Tax", "Insurance"]
    }
  }
}
```

| Field            | Type   | Description                                                                                                        |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `display_type`   | string | The scalar display type applied to slice values.                                                                   |
| `decimal_format` | string | The precision applied to slice values.                                                                             |
| `slices`         | object | `slices.names` is an array of optional [slice labels](/authoring/charts#pie-charts), or an empty array when unset. |

## Activities

Each entry in `activities` describes one [activity](/concepts/activities): its equation and which of the variables it references it may solve for.

```json theme={null}
{
  "id": "215122f5-b4b1-4512-8286-0b01682dac7d",
  "key": "act_e986dd2e74a415149c58",
  "title": "Loan – Interest Rate – Term – Payment",
  "description": "Calculates a mortgage's loan amount, interest rate, periods, or monthly payment.",
  "equation": "payment = -pmt(loan_amount; 0; interest_rate; periods; 12; 12; 0)",
  "calculable": ["loan_amount", "interest_rate", "periods", "payment"]
}
```

| Field         | Type   | Description                                                                                                                                                                                                                                                                                                        |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`          | UUID   | System-assigned identifier for the activity.                                                                                                                                                                                                                                                                       |
| `key`         | string | The activity's identifier — system-assigned, in the form `act_` followed by hex. It is not author-chosen (unlike a variable key) and is not referenced in equations. On re-import into the same domain it acts as an idempotency key: activities are matched by key to decide which to update and which to create. |
| `title`       | string | Human-readable label stating what the activity computes.                                                                                                                                                                                                                                                           |
| `description` | string | What the activity computes — documentation for the people reading the domain.                                                                                                                                                                                                                                      |
| `equation`    | string | The activity's [equation](/authoring/writing-equations) in TrueMath's expression syntax. It references variables by key; a variable comes into being the moment an equation references its key.                                                                                                                    |
| `calculable`  | array  | The variable **keys** this activity is allowed to [solve for](/authoring/writing-activities#calculable-variables). An activity may solve for any one variable in this list depending on which others are known; a variable the equation references but that is *not* listed here is only ever read as an input.    |

## How variables and activities relate

Within a definition, activities and variables are connected by **key**, with no separate wiring:

* An activity's `equation` references variables by their `key`. Reusing the same key across activities refers to the same variable — this is how activities compose into a domain. See [How activities compose](/authoring/writing-activities#how-activities-compose).
* An activity's `calculable` array lists variable keys — among the variables its `equation` references, the ones the activity may solve for, rather than only read as input.

Because the relationship is carried by key, the keys in `equation` and `calculable` must match the `key` of an entry in `variables`. The `id` fields identify existing elements; they are not how activities point at variables.

<Note>
  The read endpoint [`GET /v1/domains/:id/activities`](/api/domains) returns the same configuration in a different shape — it relates each activity to its variables through a `variable_refs` array of `variable_id`s, and adds fields such as activity `state` and a `version`. When generating or reading a portable **definition**, use the key-based shape on this page.
</Note>

## Complete example

A self-contained excerpt of a mortgage domain — scalar variables, a table, a bar chart, and a pie chart, with the activities that drive them. Every key referenced in an `equation` or `calculable` list is defined below as a variable:

```json theme={null}
{
  "domain": {
    "title": "Mortgage",
    "description": "Mortgage and home-loan calculations: home price, down payment, loan amount, interest rate, monthly payment, amortization, escrow, and related figures."
  },
  "variables": [
    {
      "id": "9e747a43-bee9-4943-9674-125f46349355",
      "key": "loan_amount",
      "title": "Loan Amount",
      "description": "The mortgage amount or amount of the loan for the property.",
      "default_value": "",
      "display_type": "number",
      "display_metadata": { "number": { "decimal_format": "decimals_2" } }
    },
    {
      "id": "484c52a2-f711-4301-b784-ac13a9e4a420",
      "key": "interest_rate",
      "title": "Interest Rate",
      "description": "Annual interest rate expressed as a percentage.",
      "default_value": "",
      "display_type": "percent",
      "display_metadata": { "number": { "decimal_format": "decimals_3" } }
    },
    {
      "id": "067f0036-52d5-47b7-8dc7-c5aa0529304a",
      "key": "periods",
      "title": "Term",
      "description": "Number of loan months or years.",
      "default_value": "30 yr",
      "display_type": "number",
      "display_metadata": { "number": { "decimal_format": "decimals_float" } }
    },
    {
      "id": "0fd3b8f8-a61e-447d-84fd-d3a35d63f145",
      "key": "payment",
      "title": "Payment",
      "description": "Mortgage or loan payment amount per month.",
      "default_value": "",
      "display_type": "number",
      "display_metadata": { "number": { "decimal_format": "decimals_2" } }
    },
    {
      "id": "8eb7362c-6839-4e9f-9629-483239b84129",
      "key": "property_taxes",
      "title": "Property Taxes",
      "description": "Annual property tax amount for the escrow payment.",
      "default_value": "",
      "display_type": "number",
      "display_metadata": { "number": { "decimal_format": "decimals_2" } }
    },
    {
      "id": "d270dd0d-7e58-43dd-9624-ab60a525e630",
      "key": "insurance",
      "title": "Insurance",
      "description": "Annual home owner's insurance amount for the escrow payment.",
      "default_value": "",
      "display_type": "number",
      "display_metadata": { "number": { "decimal_format": "decimals_2" } }
    },
    {
      "id": "7b544646-83e8-4651-8f76-4d7ca2bdf984",
      "key": "amortization",
      "title": "Amortization",
      "description": "Present an amortization table during the life of the loan.",
      "default_value": "",
      "display_type": "table",
      "display_metadata": {
        "table": {
          "start_row_index": 1,
          "columns": [
            { "name": "Payment",        "display_type": "number", "decimal_format": "decimals_2" },
            { "name": "Principal Paid", "display_type": "number", "decimal_format": "decimals_2" },
            { "name": "Interest Paid",  "display_type": "number", "decimal_format": "decimals_2" },
            { "name": "Ending Balance", "display_type": "number", "decimal_format": "decimals_2" }
          ],
          "rows": { "names": [] }
        }
      }
    },
    {
      "id": "9bfbc482-784e-42a6-8528-209ffcda08ed",
      "key": "ending_balance_chart",
      "title": "Ending Balance Pay Down Chart",
      "description": "Chart showing the ending balance at each period throughout the life of the loan.",
      "default_value": "",
      "display_type": "bar_chart",
      "display_metadata": {
        "bar_chart": {
          "series_by": "rows",
          "stacked": false,
          "x_axis": { "title": "Periods" },
          "labels": { "source": "index", "start_series_index": 1 },
          "series": [
            { "name": "Ending Balance", "display_type": "number", "decimal_format": "decimals_2" }
          ]
        }
      }
    },
    {
      "id": "72407c73-8bfc-487c-8a69-0e066520da1a",
      "key": "escrow_payment_chart",
      "title": "Escrow Payment Chart",
      "description": "Chart showing percentages of an escrow payment by principal plus interest, property taxes, and insurance.",
      "default_value": "",
      "display_type": "pie_chart",
      "display_metadata": {
        "pie_chart": {
          "display_type": "number",
          "decimal_format": "decimals_2",
          "slices": { "names": ["Payment", "Property Tax", "Insurance"] }
        }
      }
    }
  ],
  "activities": [
    {
      "id": "215122f5-b4b1-4512-8286-0b01682dac7d",
      "key": "act_e986dd2e74a415149c58",
      "title": "Loan – Interest Rate – Term – Payment",
      "description": "Calculates a mortgage's loan amount, interest rate, periods, or monthly payment.",
      "equation": "payment = -pmt(loan_amount; 0; interest_rate; periods; 12; 12; 0)",
      "calculable": ["loan_amount", "interest_rate", "periods", "payment"]
    },
    {
      "id": "a029cb79-3adc-4864-80d3-0128f126c529",
      "key": "act_3b1f9c2a7d4e0a6f8b5c",
      "title": "Amortization Table",
      "description": "Equation to present an amortization table.",
      "equation": "amortization = amortization(1; periods; loan_amount; 0; -payment; interest_rate; periods; 12; 12; 0; 1)",
      "calculable": ["amortization"]
    },
    {
      "id": "85b8b91d-15af-4255-a53d-a9b82466619d",
      "key": "act_7c0d4a9e2f1b6038d5ae",
      "title": "Ending Balance Pay Down Chart",
      "description": "Extracts the ending-balance column from the amortization table to drive the pay-down chart.",
      "equation": "ending_balance_chart = column(amortization; 4)",
      "calculable": ["ending_balance_chart"]
    },
    {
      "id": "7d558a96-1345-4b40-b13b-f8ee22d6e30c",
      "key": "act_5d2e8f1a0c7b3946e1f2",
      "title": "Escrow Payment Chart",
      "description": "Displays a pie chart showing escrow payments for the first period.",
      "equation": "escrow_payment_chart = [payment; property_taxes / 12; insurance / 12]",
      "calculable": ["escrow_payment_chart"]
    }
  ]
}
```