# What is the Safe Mode in jsoncsv for Escaping Characters?

> Discover jsoncsv's safe mode for escaping characters. Prevent ambiguous flattening and ensure lossless JSON to CSV round-trip conversion. Learn how it works.

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

---

**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`](https://github.com/alingse/jsoncsv/blob/main/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:

```python
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`](https://github.com/alingse/jsoncsv/blob/main/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`](https://github.com/alingse/jsoncsv/blob/main/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:

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

```python
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`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py)** exposes the safe mode through the `--safe` flag.

Flatten a JSON file while escaping special characters:

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

```

Restore the original structure from the flattened file:

```bash
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`](https://github.com/alingse/jsoncsv/blob/main/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`](https://github.com/alingse/jsoncsv/blob/main/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.