Tree-Structured Data

Besides spreadsheets, Archmage also reads configurations from tree-structured data files: YAML, JSON, JSON5, JS, TOML, and XML. You can freely mix spreadsheet and tree-structured config files in a single export or struct run.

Refer to the topics below for detailed specifications:

Topic	Description
Meta Nodes	Override a node’s inferred type and supply settings the data cannot express	View
Leaf and Non-Leaf Types	The two type categories a tree node falls into	View
Demo File	An optional companion file to isolate meta nodes, recover missing fields, and demonstrate field usage	View
Tree-Backed Regular Table	A file with a map of objects at its root works as a regular table	View
Conditional Export	A __condition__ field decides whether the {} node holding it is exported	View
Format-Specific Limits	Format-specific limits and restrictions	View

Choosing the Right Data Format

Spreadsheets are well-suited for large, uniform tables — many rows, fixed columns, a clear primary key. Tree-structured data files shine when the data is naturally hierarchical or irregular — deep nesting, optional fields that vary across objects.

Automatic Type Inference

During processing, Archmage infers the data type for each node automatically.

Note

For numeric nodes, inference produces int64 for integers and float64 for floating-point values. The --tree-int-type and --tree-float-type CLI flags change these defaults — int, int32, or int64 for integers, float, float32, or float64 for floats.

For most configs, this is all you need. However, not every case is that simple.

Meta Nodes

The inferred type may be technically correct but not what you want — a field containing "2001-01-02" infers as string, though you intended datetime. A meta node can override that inference and supply additional settings the data itself cannot express.

Demo File

When a field never appears anywhere in a data file, inference cannot detect it. A demo file is a companion to the data file, where you can supply the fields the data leaves out.

Null and Empty Nodes

After type inference and meta overriding, the type of some nodes may still be undetermined. Such nodes are null, empty {}, or empty [], and Archmage drops them — they appear in neither the exported data nor the generated code.

Absent Fields

In tree-structured config files, hand-crafted objects often carry different sets of fields. A field present in one object may be absent in another. When a field is absent, Archmage handles it in one of three ways:

1. Fills it with its default export value or zero value.
2. Leaves it out.
3. Reports an error.

The presence option decides which behavior to apply, and its setting applies to the whole subtree beneath the node that carries it.

Note

The default presence is implicit. Change it with the --presence CLI flag.