# What Is Dot Notation in jsoncsv Keys?

> Understand dot notation in jsoncsv keys for flattening nested JSON into CSV. Learn how jsoncsv uses dot notation to represent hierarchical data structures simply.

- Repository: [alingse/jsoncsv](https://github.com/alingse/jsoncsv)
- Tags: api-reference
- Published: 2026-02-24

---

**Dot notation in jsoncsv is the string representation of nested JSON paths created by joining object keys with a separator (default ".") during the flattening process, enabling conversion of hierarchical data to flat CSV formats.**

`jsoncsv` is an open-source Python library (alingse/jsoncsv) that transforms nested JSON objects into flat dictionaries suitable for CSV or Excel output. During this conversion, the tool creates **dot notation keys** to represent the hierarchical path to each value in a single string, ensuring every nested field maps to a unique column header.

## How Dot Notation Works in jsoncsv

When `jsoncsv` processes a nested JSON object, it expands the hierarchy into a one-dimensional dictionary where each key represents the full path to a value.

### The Flattening Process

The core logic resides in [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py), specifically the `expand` function. This function traverses nested dictionaries and concatenates keys using the configured separator.

```python
from jsoncsv.jsontool import expand

nested = {
    "user": {
        "name": "Alice",
        "address": { "city": "Paris", "zip": 75000 }
    }
}

flat = expand(nested)

# Result: {"user.name": "Alice", "user.address.city": "Paris", "user.address.zip": 75000}

```

The resulting keys—`"user.name"`, `"user.address.city"`—are the **dot notation** representation of the original nested structure.

### Separator and Escaping

By default, `jsoncsv` uses a period (`.`) as the separator, as documented in the README under the `-s, --separator` option. However, when a key in the original JSON contains the separator character itself, the tool protects it using an escape character (`\`).

The escape handling is implemented in [`jsoncsv/utils.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/utils.py) through the `encode_safe_key` and `decode_safe_key` functions (lines 15-41). For example, if you have a key literally named `"api.a.com"` with a sub-key `"p95"`, the encoded result becomes:

```python
from jsoncsv.utils import encode_safe_key, decode_safe_key

segments = ["api.a.com", "p95"]
safe_key = encode_safe_key(segments, ".")

# Returns: "api.a.com\\.p95"

original = decode_safe_key(safe_key, ".")

# Returns: ["api.a.com", "p95"]

```

This escaping ensures that literal dots in key names do not collide with the separator dots used for path notation. The test suite in [`tests/test_jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/tests/test_jsontool.py) (lines 71-76) validates this behavior with real-world edge cases.

## Working with Dot Notation in Python

You can programmatically generate and manipulate dot notation keys using the library's utility functions.

### Basic Expansion

To flatten a dictionary for CSV serialization:

```python
from jsoncsv.jsontool import expand

data = {"id": 1, "person": {"name": "Bob", "age": 30}}
flattened = expand(data)

# flattened == {"id": 1, "person.name": "Bob", "person.age": 30}

```

This output format ensures that when written to CSV, the header row contains `id,person.name,person.age`, with each column aligning to the correct data field.

### Handling Special Characters

When your data contains keys that include the dot character, use the utility functions to prevent parsing ambiguity:

```python
from jsoncsv.utils import encode_safe_key

# Encode a key containing a literal dot

key = encode_safe_key(["version", "1.0.0"], ".")

# key == "version.1\\.0\\.0"

```

To reconstruct the original nested structure from dot notation keys, use the `restore` function from [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py), which reverses the expansion process.

## Command-Line Usage Examples

The `jsoncsv` CLI automatically generates dot notation keys when using the expand flag (`-e` or default pipe):

```bash

# Default dot notation output

cat raw.json | jsoncsv > flattened.json

# With explicit separator specification

cat raw.json | jsoncsv -s "_" > flattened.json

# Convert directly to Excel with dot notation headers

cat raw.json | jsoncsv | mkexcel > output.csv

```

For the input `{"id":1, "person":{"name":"Bob","age":30}}`, the resulting CSV header will be `id,person.name,person.age`, demonstrating how dot notation preserves the JSON hierarchy in a flat format.

## Summary

- **Dot notation** in `jsoncsv` represents nested JSON paths as single strings using a separator (default `.`).
- The `expand` function in [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py) creates these keys during the flattening process.
- The `encode_safe_key` and `decode_safe_key` functions in [`jsoncsv/utils.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/utils.py) handle escaping when keys contain the separator character.
- This notation enables reliable conversion between hierarchical JSON and flat CSV/Excel formats by ensuring unique column headers for every nested field.

## Frequently Asked Questions

### What is the default separator in jsoncsv dot notation?

The default separator is a period (`.`), as implemented in the `expand` function and documented in the README. You can customize this using the `-s` or `--separator` flag in the CLI or by passing a different separator argument to the Python API functions.

### How does jsoncsv handle keys that contain the separator character?

When a key contains the separator character (e.g., a literal dot), `jsoncsv` escapes it with a backslash (`\`). The `encode_safe_key` function in [`jsoncsv/utils.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/utils.py) handles this encoding, while `decode_safe_key` reverses it during restoration, ensuring data integrity is maintained.

### Can I change the separator from a dot to something else?

Yes. While dot notation uses `.` by default, you can specify any string as the separator using the `-s` CLI option or the `separator` parameter in the Python API. This is useful when your data frequently contains dots in key names and you want to avoid excessive escaping.

### How do I convert dot notation keys back to nested JSON?

Use the `restore` function from [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py). This function takes a flattened dictionary with dot notation keys and reconstructs the original nested structure, reversing the expansion process and unescaping any protected separator characters automatically.