Unicode, accents, and UTF-8 in JSON

By Bruno J F Costa · Why “São Paulo” is legal JSON — and why it still arrives as mojibake.

JSON is a Unicode format. RFC 8259 expects UTF-8 on the modern web. You can put “São Paulo”, “açúcar”, or an emoji in a string without escaping. You can also write the same characters as \u00e3-style escapes. Both are valid. Problems start when a hop in the pipeline treats the bytes as Latin-1, Windows-1252, or “just ASCII,” then someone blames the formatter.

This guide is for people who ship Portuguese (and other non-ASCII) payloads. It is not a Unicode textbook. It is the checklist I use when a name looks fine in the browser and broken in the database dump.

Literal characters versus \\u escapes

These two strings are the same after parse:

{"city": "São Paulo"}
{"city": "S\u00e3o Paulo"}

The first is easier to read and to review in git. The second is useful when a transport or an old log viewer mangles non-ASCII, or when you need to embed a character you cannot type. JSON Quiet will keep what you give it when you format: it pretty-prints structure; it does not have to rewrite every letter into \uXXXX.

Escapes are required for a few control characters (newline, tab, backslash, quote). They are optional for “ã”. Do not “ASCII-fy” a Brazilian address unless a consumer documents that restriction. See escape sequences for the required set.

UTF-8 is the default; headers still matter

A .json file should be saved as UTF-8. HTTP APIs should send Content-Type: application/json (charset UTF-8 is implied for JSON). If a proxy or a PHP script declares ISO-8859-1 and the body is UTF-8, you get mojibake: “São” becomes “SÃ£o”. The JSON is still syntactically valid. Validation will pass. The data is wrong.

When that happens, do not “fix” it by deleting accents in the formatter. Fix the encoding at the boundary that lied. Re-decode the bytes with the correct charset, then format.

Normalization and lookalikes

Unicode allows more than one byte sequence for some letters (composed “ã” versus “a” + combining tilde). Two strings can look identical and fail a strict equality check. If you compare names from a form and a database, normalize on both sides (NFC is the usual web choice) in your application — not in a generic pretty-printer.

That is also why “search for this key” can miss a field that looks the same. Pretty-print first, then copy the exact key from the formatted output.

Emoji and surrogate pairs

Emoji are legal in JSON strings. Some older stacks still emit UTF-16 surrogate escapes (\uD83D\uDE00). Modern parsers reassemble them. If a consumer shows two replacement characters, the hop in the middle split the pair. Treat that as a stack bug, not as “JSON cannot do emoji.”

A Brazil-focused check

Paste the payload into JSON Quiet. If Validate fails, it is syntax, not accents — follow the errors guide.
If Validate succeeds but “ção” looks wrong, the file was already corrupted before you pasted. Trace Content-Type and file encoding.
Prefer literal UTF-8 in source files your team reads every day (package.json-style configs, fixtures with street names).
Use \u escapes only when a documented consumer is ASCII-only, or when you are debugging a control character.
Never “fix” a name by replacing ã with a. That is data loss, not encoding hygiene.