The domain definition

A domain has a single, portable representation: a JSON definition holding the domain’s labels, its variables, and its activities. This is the form a domain takes when you export, import, or copy 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, equations, and 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.

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: 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) for what a calculation or read endpoint returns.

Top-level structure

A definition is an object with three members:

{
  "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.
`variables`	array	Every variable in the domain — see Variables.
`activities`	array	Every activity in the domain — see Activities.

Variables and activities relate to one another by key, not by position or by id — see How variables and activities relate.

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 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.

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 keys, labels, default_values, 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.

The domain object

"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.

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.

Variables

Each entry in variables describes one variable: its key, its labels, its default, and how it is displayed.

{
  "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 — 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.
`prompt`	string	Optional, authoring-only interpretation guidance 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, sharing, or MCP response.
`default_value`	string	The default 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 below.
`display_metadata`	object	The display configuration, keyed by the variable’s structural type — see display_metadata.

Display types

display_type is one of:

Value	Meaning
`number`	A plain number, shown with thousands separators and the unit 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.
`bar_chart`	A table presented as a bar chart — see Charts.
`pie_chart`	A table presented as a pie chart — see 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:

"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.

Table variables — `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": [] }
  }
}

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.
`columns`	array	The table’s columns. Columns are defined; rows are data — see Tables. 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, 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.

Bar chart variables — `bar_chart`

A chart is a presentation of a table; the variable’s value stays a table and display_metadata.bar_chart configures how it is drawn.

"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 uses.

Pie chart variables — `pie_chart`

"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, or an empty array when unset.

Activities

Each entry in activities describes one activity: its equation and which of the variables it references it may solve for.

{
  "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 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. 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.
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.

The read endpoint GET /v1/domains/:id/activities returns the same configuration in a different shape — it relates each activity to its variables through a variable_refs array of variable_ids, 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.

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:

{
  "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"]
    }
  ]
}

Introduction

Quickstart

Concepts

Domain Library

Playground

Authoring Domains

Data Types

Units

Function Library

API Reference

Resources

The domain definition

Top-level structure

The domain object

Variables

Display types

display_metadata

Scalar variables — `number`

Table variables — `table`

Bar chart variables — `bar_chart`

Pie chart variables — `pie_chart`

Activities

How variables and activities relate

Complete example

​Top-level structure

​The domain object

​Variables

​Display types

​display_metadata

​Scalar variables — number

​Table variables — table

​Bar chart variables — bar_chart

​Pie chart variables — pie_chart

​Activities

​How variables and activities relate

​Complete example

Top-level structure

The domain object

Variables

Display types

display_metadata

Scalar variables — `number`

Table variables — `table`

Bar chart variables — `bar_chart`

Pie chart variables — `pie_chart`

Activities

How variables and activities relate

Complete example