The flatten algorithm walks the JSON tree depth-first. Each leaf value (a string, number, boolean, or null) becomes a CSV cell, and the column name is the path from the root to the leaf, joined with the chosen separator. The path { customer: { address: { city: "London" } } } produces a column named customer.address.city with the value London. This convention scales to arbitrary depth and is the same approach used by pandas json_normalize, jq path expressions, and most data warehouses.
Arrays are the interesting case. When an array contains primitives, the array becomes a JSON-encoded cell by default, preserving the values without exploding the row count. When an array contains objects, you have a choice: JSON-encode the whole array as a cell, explode each element into a separate row by duplicating parent fields, or include only the first element flattened with an index suffix. Each choice has trade-offs. JSON-encoding preserves information but is opaque to spreadsheets. Exploding produces analyst-friendly rows but multiplies row count. Index-suffixing produces a fixed-width row at the cost of dropping array elements beyond the first.
Maximum depth is the dial that prevents column explosion. A JSON tree with five levels of branching, three keys per level, produces 243 leaf paths if all branches are present. Most analysts get overwhelmed by more than 50 columns. Capping depth at 2 or 3 produces a manageable column count while preserving the most-used fields, and remaining depth stays as JSON-encoded cells that can be re-parsed if needed. FixTools shows the projected column count for each depth setting so you can pick the right one before downloading.
Underscore vs dot separator is mostly a downstream-tool consideration. Dots are more readable for humans but conflict with some SQL dialects where dot is the table-column separator. Underscores are uglier but universally accepted in column names. If your downstream is BigQuery or Snowflake, dots work fine. If your downstream is older Postgres or MySQL, switch to underscores to avoid quoting issues.