Are multi-line strings allowed in JSON?
Master System Design with Codemia
Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.
Introduction
No, JSON does not allow multi-line strings. The JSON specification (RFC 8259) requires that strings be contained on a single line, with special characters like line breaks represented using escape sequences such as \n. This is one of the most common sources of confusion for developers working with JSON for the first time, so let's break down exactly how to handle multi-line text in JSON and what alternatives exist.
What the JSON Spec Says About Strings
A JSON string is a sequence of zero or more Unicode characters wrapped in double quotes. The spec explicitly forbids unescaped control characters inside strings, and that includes newline characters (U+000A) and carriage returns (U+000D).
This means the following is invalid JSON:
Any JSON parser will reject this with a syntax error. The string must stay on one line, or you need to use escape sequences.
How to Represent Multi-line Text in JSON
Method 1: Use \n Escape Sequences
The standard approach is to replace actual line breaks with \n inside the string:
When an application reads this string and renders it, the \n characters produce actual line breaks. You can also use \r\n for Windows-style line endings:
Method 2: Use an Array of Strings
For long multi-line content, many developers prefer splitting the text into an array and joining it at read time:
Then in your application code, join them:
This approach keeps the JSON file itself readable, which matters when humans edit it by hand.
Method 3: Let Your Language Handle Serialization
Most programming languages automatically escape line breaks when serializing to JSON. You rarely need to manually insert \n characters.
Python:
JavaScript / Node.js:
Java:
Allowed Escape Sequences in JSON Strings
Here is the complete list of escape sequences the JSON spec permits inside strings:
| Escape Sequence | Meaning |
\" | Double quote |
\\ | Backslash |
\/ | Forward slash (optional) |
\b | Backspace |
\f | Form feed |
\n | Newline (line feed) |
\r | Carriage return |
\t | Tab |
\uXXXX | Unicode character (hex code) |
No other escape sequences are valid. Notably, \a, \v, and \0 are not supported and will cause parse errors.
Alternatives That Do Support Multi-line Strings
If you find JSON's string limitations frustrating, consider these formats for configuration files or data storage where multi-line strings are common:
| Format | Multi-line Syntax | Example Use Cases |
| YAML | Block scalars with | or > | Config files, Kubernetes manifests |
| TOML | Triple-quoted """ | Rust's Cargo.toml, Python pyproject |
| JSON5 | Backtick strings, trailing commas | Developer tooling configs |
| JSONC | Comments allowed, same string rules | VS Code settings.json |
| XML | CDATA sections | Legacy APIs, SOAP |
YAML example:
TOML example:
Note that JSON5 and JSONC extend JSON but are not standard JSON. Most APIs and data exchange protocols expect strict RFC 8259 JSON.
Common Pitfalls
- Pasting multi-line text into a JSON file directly. Your editor will not complain, but the JSON is invalid. Always run it through a validator or serializer.
- Confusing
\nin source code with\nin JSON. In many languages,"\n"in a string literal is already a newline character. When serialized to JSON, it becomes the two-character escape sequence\n. If you write"\\n"in your source code, you get a literal backslash-n in the output, not a line break. - Using single quotes. JSON requires double quotes for strings.
{'key': 'value'}is not valid JSON. - Forgetting
\ron Windows. If your source text uses\r\nline endings but you only escape with\n, round-tripping the data may strip carriage returns. - Trailing commas. While not specific to multi-line strings, trailing commas in JSON arrays or objects are invalid. This is a common mistake when splitting long text into arrays.
Summary
- JSON does not allow multi-line strings. This is by design in the RFC 8259 specification.
- Use
\nescape sequences to represent line breaks within a JSON string value. - For human-readable JSON files, consider splitting text into an array of strings and joining at read time.
- Let your programming language's JSON serializer handle escaping automatically rather than doing it by hand.
- If your use case demands actual multi-line strings in a config file, consider YAML, TOML, or JSON5 instead of standard JSON.
- Always validate your JSON with a parser after manual editing to catch unescaped line breaks.

