# JSON Encoding Standards for Blog/Data Files

**Last Updated:** 2026-02-11

Canonical standards for writing JSON files in `docs/content/blog/posts/**/data/` and `v2/data/blog/`.

## Rule

All scripts that write JSON data files must use:

```php
json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
```

Or use the shared constant (after requiring `v2/config/blog-json-constants.php`):

```php
json_encode($data, JSON_ENCODE_READABLE);
```

## Rationale

| Flag | Purpose |
|------|---------|
| `JSON_PRETTY_PRINT` | Human-readable indentation |
| `JSON_UNESCAPED_UNICODE` | Keep German umlauts (ü, ä, ö), quotes („"), etc. as literal characters instead of `\u00fc`, `\u00e4`, `\u201e` |
| `JSON_UNESCAPED_SLASHES` | Keep URLs like `post_url: "/insights/lexikon/slug/"` instead of `"\/insights\/lexikon\/slug\/"` |

## Scope

- `keywords-sistrix.json` – post_url, German keywords
- `faq-research.json`, `serp-features.json`, `competitor-analysis.json` – may contain Unicode
- Any JSON in `docs/content/blog/posts/**/data/` or `v2/data/blog/posts/**/`

## Remediation

If files were corrupted (e.g. by a script that wrote without these flags):

```bash
php v2/scripts/blog/remediate-json-encoding.php --backup
```

## References

- [PHP json_encode manual](https://www.php.net/manual/en/function.json-encode.php)
- [BLOG_CONTENT_EDIT_WORKFLOW.md](../content/blog/BLOG_CONTENT_EDIT_WORKFLOW.md) – rationale for programmatic edits
- [v2/config/blog-json-constants.php](../../v2/config/blog-json-constants.php) – `JSON_ENCODE_READABLE` constant