What Is Dot Notation in jsoncsv Keys?

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, specifically the expand function. This function traverses nested dictionaries and concatenates keys using the configured separator.

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 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:

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 (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:

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:

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, 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):

# 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 creates these keys during the flattening process.
• The encode_safe_key and decode_safe_key functions in 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}