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 carry server-side fields such as identity and version. 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 four members:

{
  "definition_schema_version": 2,
  "domain":    { "title": "...", "description": "..." },
  "variables": [ /* one entry per variable */ ],
  "activities": [ /* one entry per activity */ ]
}

Member	Type	Description
`definition_schema_version`	integer	The version of the definition format the file was written in. An export includes it. A file without one is read as the current version, so you can leave it out when generating a definition. Keep the value an exported file has: a file marked `1` is read with the earlier meaning of a bar chart’s `series_by`, which named the other axis.
`domain`	object	The domain’s details — see The domain object.
`variables`	array	The domain’s variables — 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, unit_options, and display configuration, plus each activity’s equation and variable_refs. You can also omit definition_schema_version. 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 is not part of 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": "",
  "kind": "percent",
  "display_metadata": {
    "number": { "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.
`kind`	string	What the value is — one of the kinds below.
`display_metadata`	object	The display configuration, keyed by the variable’s structural type — see display_metadata.
`unit_options`	array	The suggested units for the variable, in order — see Unit options below. Present only on a `number` or `no_separator` variable that has any, and absent otherwise; a table has one list per column instead. Unlike `prompt`, it is returned by the public API.

Kinds

A variable’s kind says what its value is. How the value is read on input, how it is shown, and which vocabulary its format is drawn from all follow from it. It 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.
`duration`	A span of time, held as a count of seconds — see Authoring dates and durations.
`date`	A calendar day, held as a count of seconds from the Unix epoch.
`datetime`	A calendar day and a clock time, held the same way.
`time`	A time of day, held as a count of seconds from midnight.
`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.

Unit options

unit_options is a list of suggested units for the variable, in order, the first being its primary unit. It is a suggestion, not a restriction: a calculation can use any unit TrueMath recognizes whatever the list says. See Unit options.

{
  "key": "loan_term",
  "title": "Term",
  "description": "The length of the loan.",
  "default_value": "30 yr",
  "kind": "number",
  "unit_options": ["yr", "mo"],
  "display_metadata": { "number": { "format": "decimals_0" } }
}

The field is absent, not an empty array, when a variable has no unit options. Each entry is a canonical unit code from the unit catalog; an alias you write is canonicalized on save, so "feet" is stored as "ft". The list sits at the top level of the variable, beside kind, and only a number or no_separator variable can have one. For table, each entry of display_metadata.table.columns[] has its own, under the same rules. Publishing refuses a list on a kind that cannot have one, a list with a unit TrueMath does not recognize, and a list with the same unit twice. Nothing connects a list to default_value: a variable can default to 30 yr and offer only ["mo"]. See Unit options.

display_metadata

display_metadata holds the variable’s display configuration under a single key naming its structural type. Every scalar kind — number, percent, no_separator, and the four time kinds — nests under number; the others nest under table, bar_chart, or pie_chart.

Scalar variables — `number`

For number, percent, no_separator, duration, date, datetime, and time:

"display_metadata": {
  "number": { "format": "decimals_2" }
}

Field	Type	Description
`format`	string	How the value is rendered, from the vocabulary its `kind` takes. Display only — the stored value keeps full precision.

For number, percent, and no_separator that vocabulary is a decimal count: 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). For the four date and time kinds the same slot holds a format token matching the kind — date_med for a date, duration_hms for a duration. A token from the wrong vocabulary is rejected on save. See Choosing a format for the full list.

"display_metadata": {
  "number": { "format": "date_med" }
}

For those four kinds a default_value is stored as a combined "value unit" string in seconds — "1784592000 s" — or as the literal word today or now. You author it in the form you would write by hand; see Setting a default.

Table variables — `table`

"display_metadata": {
  "table": {
    "start_row_index": 1,
    "columns": [
      { "name": "Payment",        "kind": "number", "format": "decimals_2", "unit_options": ["USD"] },
      { "name": "Principal Paid", "kind": "number", "format": "decimals_2", "unit_options": ["USD"] },
      { "name": "Interest Paid",  "kind": "number", "format": "decimals_2", "unit_options": ["USD"] },
      { "name": "Ending Balance", "kind": "number", "format": "decimals_2", "unit_options": ["USD"] }
    ],
    "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), `kind` (any scalar kind: `number`, `percent`, `no_separator`, `duration`, `date`, `datetime`, or `time`), `format` from that kind’s vocabulary, and, on a `number` or `no_separator` column, its own `unit_options`. Those four keys are all a column can have.
`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. A column’s unit_options is not a unit either, and a cell can hold any unit whatever that list says.

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": "columns",
    "stacked": false,
    "x_axis": { "title": "Periods" },
    "labels": { "source": "index", "start_series_index": 1 },
    "series": [
      { "name": "Ending Balance", "kind": "number", "format": "decimals_2" }
    ]
  }
}

Field	Type	Description
`series_by`	string	What one series is. `"columns"` plots each column of the underlying table as a series, leaving each row an x-axis category; `"rows"` plots each row, leaving each column a category. Required. See Series orientation.
`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"` (a running number) or `"first_series"` (the table’s first series, which then supplies the labels instead of a plotted bar). `start_series_index` is the number those labels count up from.
`series`	array	One entry per plotted series, each with `name`, `kind`, and `format` — the same scalar formatting a column uses, the four time kinds included. When `labels.source` is `"first_series"`, the first entry describes the label series rather than a plotted one.

Pie chart variables — `pie_chart`

"display_metadata": {
  "pie_chart": {
    "kind": "number",
    "format": "decimals_2",
    "slices": {
      "names": ["Payment", "Private Mortgage Insurance", "Property Tax", "Insurance"]
    }
  }
}

Field	Type	Description
`kind`	string	The scalar kind applied to slice values, the four time kinds included.
`format`	string	How slice values are rendered, from that kind’s vocabulary.
`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, the variables it uses in order, and which of them 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)",
  "variable_refs": [
    { "variable_key": "loan_amount",   "calculable": true },
    { "variable_key": "interest_rate", "calculable": true },
    { "variable_key": "periods",       "calculable": true },
    { "variable_key": "payment",       "calculable": true }
  ]
}

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.
`state`	string	`active` or `disabled` — see Disabling an activity. Absent means `active`, so the field appears only on a disabled activity. Deleted activities are not part of a definition.
`variable_refs`	array	The variables this activity uses, in order, each an object `{ "variable_key", "calculable" }`. The order is the order the read endpoints and calculation responses return the activity’s variables in, so set it deliberately. `calculable` is `true` for a variable the activity may solve for: an activity may solve for any one variable marked `true`, depending on which others are known. A variable marked `false` is only ever read as an input.

How variables and activities relate

Within a definition, activities and variables are connected by key:

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 variable_refs names the same variables by key, in order, and marks which of them the activity may solve for.

Every key in equation and in variable_refs must match the key of an entry in variables. The id fields identify existing elements; they are not how activities point at variables. On import, a definition that does not match these rules is filled in rather than rejected:

A variable in variable_refs that the equation does not use stays part of the activity. The equation does not read it.
A key the equation uses but variable_refs omits is added after the listed entries, with calculable set to false.
An activity with no variable_refs, or with an empty array, takes its variables from the equation, in the order they first appear. With no variable_refs provided, only a variable written alone on one side of the equation is marked calculable.
A key with no entry in variables becomes a blank number variable, unless the domain you import into already has a variable with that key.

The read endpoint GET /v1/domains/:id/activities returns each activity’s variable_refs in the same order, but names each variable by variable_id instead of variable_key. Use the key-based shape on this page when generating or reading a portable definition.

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 variable_refs array is defined below as a variable:

{
  "definition_schema_version": 2,
  "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": "",
      "kind": "number",
      "unit_options": ["USD"],
      "display_metadata": { "number": { "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": "",
      "kind": "percent",
      "display_metadata": { "number": { "format": "decimals_3" } }
    },
    {
      "id": "067f0036-52d5-47b7-8dc7-c5aa0529304a",
      "key": "periods",
      "title": "Term",
      "description": "Number of loan months or years.",
      "default_value": "30 yr",
      "kind": "number",
      "unit_options": ["yr", "mo"],
      "display_metadata": { "number": { "format": "decimals_float" } }
    },
    {
      "id": "0fd3b8f8-a61e-447d-84fd-d3a35d63f145",
      "key": "payment",
      "title": "Payment",
      "description": "Mortgage or loan payment amount per month.",
      "default_value": "",
      "kind": "number",
      "unit_options": ["USD"],
      "display_metadata": { "number": { "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": "",
      "kind": "number",
      "unit_options": ["USD"],
      "display_metadata": { "number": { "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": "",
      "kind": "number",
      "unit_options": ["USD"],
      "display_metadata": { "number": { "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": "",
      "kind": "table",
      "display_metadata": {
        "table": {
          "start_row_index": 1,
          "columns": [
            { "name": "Payment",        "kind": "number", "format": "decimals_2", "unit_options": ["USD"] },
            { "name": "Principal Paid", "kind": "number", "format": "decimals_2", "unit_options": ["USD"] },
            { "name": "Interest Paid",  "kind": "number", "format": "decimals_2", "unit_options": ["USD"] },
            { "name": "Ending Balance", "kind": "number", "format": "decimals_2", "unit_options": ["USD"] }
          ],
          "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": "",
      "kind": "bar_chart",
      "display_metadata": {
        "bar_chart": {
          "series_by": "columns",
          "stacked": false,
          "x_axis": { "title": "Periods" },
          "labels": { "source": "index", "start_series_index": 1 },
          "series": [
            { "name": "Ending Balance", "kind": "number", "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": "",
      "kind": "pie_chart",
      "display_metadata": {
        "pie_chart": {
          "kind": "number",
          "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)",
      "variable_refs": [
        { "variable_key": "loan_amount",   "calculable": true },
        { "variable_key": "interest_rate", "calculable": true },
        { "variable_key": "periods",       "calculable": true },
        { "variable_key": "payment",       "calculable": true }
      ]
    },
    {
      "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)",
      "variable_refs": [
        { "variable_key": "amortization",  "calculable": true },
        { "variable_key": "periods",       "calculable": false },
        { "variable_key": "loan_amount",   "calculable": false },
        { "variable_key": "payment",       "calculable": false },
        { "variable_key": "interest_rate", "calculable": false }
      ]
    },
    {
      "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)",
      "variable_refs": [
        { "variable_key": "ending_balance_chart", "calculable": true },
        { "variable_key": "amortization",         "calculable": false }
      ]
    },
    {
      "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]",
      "variable_refs": [
        { "variable_key": "escrow_payment_chart", "calculable": true },
        { "variable_key": "payment",              "calculable": false },
        { "variable_key": "property_taxes",       "calculable": false },
        { "variable_key": "insurance",            "calculable": false }
      ]
    }
  ]
}

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

Kinds

Unit options

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

​Kinds

​Unit options

​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

Kinds

Unit options

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