Skip to main content
Everything you author lives in a draft. Calculations through the API and the Playground run only against the published version. Testing a draft and then publishing it is how the work you do in the builder becomes live. See Versioning.

​
Testing a draft

You test a draft in the builder’s Test view, before publishing it. The Test view provides a form for entering values for the domain’s variables, runs the calculation against the draft, and shows the result. Scalar and unit values are shown with the display you configured for each variable. Tables and charts are output as TrueMath-formatted tables. Testing against the draft is the only way to run a domain before it is published — the public API never calculates against a draft. Use it to confirm that:
  • Activities solve in the directions you intend — each question you expect the domain to answer resolves to a value, which depends on having marked the right variables calculable.
  • Defaults apply as expected — variables fall back to their default values when you leave them blank.
  • Units resolve — values combine as intended, and incompatible combinations are rejected rather than coerced. See Combining types.
  • Results display correctly — numbers, percentages, tables, and charts read the way you configured them.
Round-trip each variable to catch drift. When an activity can solve for more than one of its variables, take a scenario you trust and re-derive each variable from the others. In the Test view, every calculable variable has a ? button that recalculates it in place — tap it on each one and watch the value. Because activities are reversible, it should not change. If a value shifts when you solve for it a different way, the domain has drift. Track it down and fix it before publishing.

​
Common validation errors

When a test calculation fails, the Test view shows the error rather than a result. Most failures fall into a handful of categories, each with a clear fix in the draft. The same conditions surface over the API as machine-readable codes — see Errors for the full catalog and the codes to branch on. An equation won’t compile. A variable definition or activity equation contains a syntax error — an unbalanced parenthesis, a stray operator, a malformed function call. Fix the equation text. Over the API this is input.syntax_error, which carries an offset to the character position of the fault. Units don’t combine. The equation mixes units that are not dimensionally compatible — adding meters to seconds, or comparing a length to an area. Either correct the units on the variables involved, or convert explicitly within the equation. A unit you typed may also be unrecognized. See Combining types. Over the API: input.incompatible_units, input.invalid_unit, and input.incompatible_type. A name or argument is invalid. A variable name is empty or uses illegal characters — names must start with a letter and contain only letters, numbers, and underscores — or a function was called with the wrong number or type of arguments, or a table is malformed (ragged rows, or a table nested in a table). Correct the name, the call, or the table shape. Over the API: input.invalid_variable_name, input.invalid_argument, input.invalid_dimensions. A variable can’t be reached. A test references a variable that no equation defines, or an equation depends on itself through a cycle. Define the missing variable, or break the dependency loop. Over the API: calculation.undefined_variable and calculation.circular_reference. The target can’t be solved, or solves to more than one value. The inputs you supplied are not enough to reach the variable you asked for, or they over-determine it — the same target resolves to conflicting values. For an unsolvable target, supply more inputs or mark the variables you expect to solve for as calculable; the error lists which inputs would unblock it. For a conflict, this usually signals drift — re-derive the value the way the Tip above describes and reconcile the activities that disagree. Over the API: calculation.unable_to_resolve_target and calculation.conflicting_results. A numeric result is undefined. Evaluation produced a divide-by-zero, an infinity, a NaN, or a value outside a variable’s valid range. Guard the equation against the offending input, or widen the range if the value is legitimate. Over the API: the math.* codes.

​
Publishing

Publishing promotes the draft to the published version. From that point, the API and Playground calculate against it. A domain can have both a published version and a newer draft at once — the API reports this with has_published and has_draft (see Domains) — and the published version keeps serving until you publish again. Republishing after edits is a deliberate step: calculation logic never changes silently underneath the callers using a domain. When business logic changes, you edit the draft, test it, and publish a new version on purpose. Combined with provenance, this is what lets a result be tied to the exact logic that produced it. You publish and revert from the same Publish view. Reverting a draft discards its unpublished changes and returns the draft to the published version — useful when you want to abandon in-progress edits rather than promote them.

​
Before you publish

A quick checklist:
  • Descriptions are legible — the domain and its variables have descriptions written in the language users use, since clear descriptions improve natural-language and agent results; activities have clear titles and descriptions for the people reading the domain.
  • Calculable coverage — the variables you expect to solve for are marked calculable on the activities that produce them.
  • Defaults are set where a variable should have a fallback value.
  • Representative scenarios pass in the Test view, including the what-if directions you expect callers to use.

​
After publishing

Editing a published domain starts a new draft; the published version continues to serve calculations until you publish the draft. To retire a domain entirely, archive it — see Archiving and Versioning.