Creating a domain

A domain is the self-contained model you author and target when you run a calculation. Creating one gives you a draft — a working copy you build up and later publish. Calculations only ever run against the published version, so a new domain is yours to shape until you decide it is ready. See Versioning.

​

What you set when you create a domain

• Title and description — human- and agent-readable labels. The description is more than display text: clear, precise descriptions improve natural-language and agent results. Write it precisely, the way you would write the one line a search engine will index.
• Identity — TrueMath assigns a stable unique identifier (UUID) (the domain_id you pass to the API) and a stable key. You do not choose these; they identify the domain for as long as it exists. The UUID is how you reference the domain through the API; the key is how TrueMath recognizes the same domain across accounts when you copy it. The key is not part of a domain’s exported definition. See Managing a domain and Domains.

​

How a domain takes shape

A domain is a set of activities and the variables they relate. You build it from the activities outward:

1. Write activities. Each activity is an equation that relates a set of variables. See Writing activities.
2. Write the equations. The expression syntax — literals, operators, functions, and units. A variable first comes into being when an equation references it. See Writing equations.
3. Define the variables. Configure each variable’s display, default, and unit. See Defining variables.
4. Add tables and charts where a variable holds more than one value or is presented visually. See Tables and Charts.
5. Test and publish. Verify the domain calculates as expected, then publish the draft. See Testing and publishing.

​

Where a domain starts

• From scratch — an empty draft you build up from your own activities and variables.
• From a library domain — start from a pre-built domain and adapt it to your conventions and business logic. See Customizing a library domain and the Domain library.
• From a JSON definition — import an existing domain definition. See Managing a domain.

​

Managing a domain

Beyond editing its activities and variables, a domain can be exported, imported, copied, and archived. A domain’s exported definition carries its activities and variables, but not its identity — neither the UUID nor the key. Identity matters when you copy a domain between accounts: the copy shares the source’s key (under its own UUID in the destination), which is how TrueMath recognizes the two as the same domain and updates the copy in place rather than duplicating it.

​

Export and import JSON

A domain’s full definition can be exported as JSON — the complete set of activities and variables, ready to copy. See The domain definition for the structure of that JSON. Importing accepts a pasted JSON definition and shows a comparison of the changes against the domain you are importing into before you accept them, so you can review exactly what an import will add, remove, or alter rather than applying it blind. An import overrides the domain you selected: the definition carries no key, so it is your selection — not anything in the JSON — that determines which domain is replaced.

​

Copy to another account

If you belong to more than one account, you can copy a domain to a different account. This is how a domain authored in one account is brought into another. The option is available to the domain’s owner. The copy shares the source domain’s key but takes its own UUID in the destination account, so copying the same domain again later updates that copy rather than creating a second one — the key is what TrueMath matches on to recognize the two as the same domain.

​

Archiving

Archiving retires a domain and hides it from use, the final stage of the domain lifecycle. An archived domain is no longer returned by the API or available in the Playground.