What is the Safe Mode in jsoncsv for Escaping Characters?

jsoncsv's safe mode escapes backslashes and separator characters in JSON keys to prevent ambiguous flattening and ensure lossless round-trip conversion between nested JSON and flat CSV formats.

When flattening nested JSON data into CSV format, special characters in object keys can corrupt the structure or make restoration impossible. The jsoncsv library solves this with a safe mode that automatically escapes problematic characters during the conversion process.

How Safe Mode Works in jsoncsv

By default, jsoncsv joins nested path components using a separator (typically .) to create flat keys. If a key contains this separator character, the resulting flat key becomes ambiguous. For example, a key named a.b nested under c could be confused with a path c.a.b.

When safe mode is enabled via the safe=True parameter or the --safe CLI flag, the library applies an escaping algorithm that preserves the original key structure.

The Escaping Algorithm

Safe mode performs two critical transformations in the encode_safe_key function located in jsoncsv/utils.py (lines 15-19):

1. Escapes backslashes by doubling them (\ becomes \\)
2. Escapes the separator by prefixing it with a backslash (. becomes \.)

The implementation joins path components only after escaping each component individually:

def encode_safe_key(path, separator):
    # Escape backslashes in each component

    path = [p.replace('\\', '\\\\') for p in path]
    # Create escaped separator for joining

    escaped_sep = '\\' + separator
    return escaped_sep.join(path)

Restoration with decode_safe_key

During the restoration process, the decode_safe_key function in jsoncsv/utils.py (lines 21-42) reverses the encoding by parsing escaped sequences and reconstructing the original path components. This ensures that keys containing dots or backslashes are restored to their exact original values.

Using Safe Mode in Python

The expand and restore functions in jsoncsv/jsontool.py accept a safe boolean parameter that delegates to the encoding utilities.

Flattening JSON with Safe Mode

Use expand with safe=True to generate escaped flat keys:

from jsoncsv.jsontool import expand

data = {
    "a.b": {"c\\d": 1},
    "e": 2
}

# Safe mode escapes special characters in keys

flat = expand(data, safe=True)
print(flat)

# Output: {'a\\.b.c\\\\d': 1, 'e': 2}

In this output, a\.b represents the original key a.b with the dot escaped, and c\\d represents c\d with the backslash doubled.

Restoring Nested Structure

Use restore with safe=True to correctly parse escaped keys and rebuild the original nested structure:

from jsoncsv.jsontool import restore

flat = {'a\\.b.c\\\\d': 1, 'e': 2}

# Safe mode decodes escaped keys

original = restore(flat, safe=True)
print(original)

# Output: {'a.b': {'c\\d': 1}, 'e': 2}

Command-Line Usage

The CLI interface in jsoncsv/main.py exposes the safe mode through the --safe flag.

Flatten a JSON file while escaping special characters:

cat input.json | jsoncsv --safe expand > flat.csv

Restore the original structure from the flattened file:

cat flat.csv | jsoncsv --safe restore > restored.json

The --safe flag ensures that keys containing dots or backslashes survive the round-trip conversion without ambiguity.

Summary

• Safe mode in jsoncsv prevents key collision by escaping backslashes and separator characters during JSON flattening.
• The encode_safe_key function in jsoncsv/utils.py doubles backslashes and prefixes separators with backslashes before joining path components.
• The decode_safe_key function reverses this process during restoration to recover the original key names.
• Enable safe mode in Python by passing safe=True to expand and restore in jsoncsv/jsontool.py.
• Use the --safe flag on the command line to process files with special characters in keys.

Frequently Asked Questions

What characters does jsoncsv safe mode escape?

Safe mode escapes two specific characters: the backslash (\) and the separator (default is .). Backslashes are doubled (\\), and separators are prefixed with a backslash (\.). This ensures that keys containing these characters can be flattened and restored without ambiguity.

Is safe mode enabled by default in jsoncsv?

No, safe mode is disabled by default. The safe parameter defaults to False in both the expand and restore functions. You must explicitly set safe=True in Python or use the --safe flag on the command line to enable character escaping.

Can I use a custom separator with safe mode?

Yes, safe mode works with custom separators. The expand and restore functions accept a separator parameter (defaulting to .). When safe mode is enabled, the library automatically escapes whatever separator character you specify, allowing you to use characters like _, |, or / while still protecting keys that contain those characters.

How does safe mode affect performance?

Safe mode adds a small computational overhead because it requires iterating through each path component to escape backslashes and separators during flattening, and parsing escaped strings during restoration. However, for most datasets, this overhead is negligible compared to the I/O operations of reading and writing JSON or CSV files. The trade-off ensures data integrity when keys contain special characters.

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