Skip to main content
A variable is a named value within a domain — a home price, an interest rate, a monthly payment. Variables are what activities relate, and what you provide and receive when you run a calculation.

​
What a variable has

A variable is defined in a domain and takes on a value when a calculation runs. As defined, a variable has:
  • A key — an identifier, unique within the domain. You reference a variable by its key when you provide or solve for it (see Input formats), and the API returns it on each variable.
  • A title and description — human- and agent-readable labels.
  • A kind and a format — what the value is, and how it is shown (see below).
  • A default value — an optional value and unit used when none is provided.
  • Unit options — an optional list of suggested units for the variable, in order (see below).
When a calculation runs, each variable also has:
  • A value — the number or table it currently holds, with its unit where applicable; the unit is part of the value (see Units and precision).
  • Provenance — where that value came from: user-stated, calculated, carried forward, or a default. See Provenance.

​
Kinds and formats

A variable holds one of TrueMath’s value types — a scalar number, a unit number, or a table — and its kind says what that value is:
  • number — a plain number, shown with thousands separators. A monetary amount is a number whose unit is a currency (for example USD).
  • percent — a rate shown as a percentage.
  • no_separator — a number shown without thousands separators (for example, a year).
  • duration, date, datetime, time — a span of time, a calendar day, a day with a clock time, or a time of day. Each is an ordinary number counting seconds. See Authoring dates and durations.
  • table — a collection of values with named rows and columns.
  • bar_chart / pie_chart — a table presented as a chart.
The variable’s format says how that value is shown, from the vocabulary its kind takes: a number of decimal places for a number, percent, or no_separator, and a date or duration format token for the four time kinds. A format applies to display only. The stored value keeps full precision.

​
Unit options

A variable can have unit options: a list of suggested units, in order.
These are the units an application should offer for the variable. A loan term is usually given in years or months, a dollar amount in USD. The order is the author’s, and the first unit is the primary unit. There is no separate setting for it. The list is a suggestion, not a restriction. A calculation can use any unit TrueMath recognizes, and dimensional validation is unchanged: 3562 days is a valid loan term, just not one a form has to offer. This matters most in natural language, where people write in whatever unit they are thinking in. A variable does not need unit options. Without them, the application decides which units to offer. Only two kinds have unit options: number and no_separator, whose values are plain numbers that can hold a unit. A percent is always a bare decimal, and the four date and duration kinds are always counts of seconds shown through a format token, so there is nothing to offer for those. A table variable has no unit options of its own. Its columns each have their own instead, one list per column, because a table is filled in a column at a time. A chart has none: a chart is output, not something a person fills in. Currency units in the list are also how money is marked. There is no money kind: an amount in dollars is a number whose value holds USD, and listing USD as a unit option is how an application can tell the field is money. See Reading unit options. For how values combine across types, see Combining types. For authoring variables, see Defining variables.
To list the variables in a published domain, use GET /v1/domains/:id/variables.