Line Break Problems in Multi-line JSON Strings

Standard JSON does not support raw multi-line string literals. If you need a line break in JSON, the JSON text must contain an escaped newline such as \n or \r\n, or you should let a JSON library escape a normal multi-line string for you.

That distinction is the source of most confusion: the JSON source must contain escape sequences, but after parsing, your application receives a normal string value with actual line breaks. Bugs usually appear when raw text is pasted into a JSON file, a JSON string is embedded inside another language string literal, or a UI renders escaped JSON text instead of the parsed value.

Can JSON have multi-line strings?

Not as raw text. The JSON specification (RFC 8259) says that JSON strings cannot contain unescaped control characters. That includes line feed (\n) and carriage return (\r), so typing a real newline directly inside the quoted string makes the JSON invalid.

{
  "message": "First line
Second line"
}

{
  "message": "First line\nSecond line"
}

How to add a line break in JSON

1. When writing JSON by hand

If you are editing a .json file directly, use \n where you want the line break:

{
  "title": "Release notes",
  "body": "Fixed line ending bug\nAdded CRLF normalization\nImproved validation"
}

2. When you already have multi-line text in code

Native strings in many languages can contain real newlines. The safe approach is to keep the string in its normal form and let a JSON serializer escape it.

// JavaScript
const body = `Fixed line ending bug
Added CRLF normalization
Improved validation`;

const payload = JSON.stringify({ title: "Release notes", body });

console.log(payload);
// {"title":"Release notes","body":"Fixed line ending bug\nAdded CRLF normalization\nImproved validation"}

# Python
import json

body = """Fixed line ending bug
Added CRLF normalization
Improved validation"""

payload = json.dumps({"title": "Release notes", "body": body})

print(payload)
# {"title": "Release notes", "body": "Fixed line ending bug\nAdded CRLF normalization\nImproved validation"}

JSON text vs parsed string value

This is the key mental model: JSON text on disk or on the wire uses escape sequences, while the parsed value in memory contains actual newline characters.

// JavaScript
const jsonText = '{"message":"First line\nSecond line"}';
const data = JSON.parse(jsonText);

console.log(data.message);
// First line
// Second line

If you inspect jsonText, you will see the backslash escape. If you inspect data.message, you will get a real multi-line string.

Common line break problems and fixes

1. Raw multi-line text was pasted into a JSON file

This is the most common failure. Someone pastes a paragraph directly between double quotes, and the file stops parsing. Replace the real line breaks with \n, or rebuild the JSON with a serializer.

2. One backslash or two?

If you are editing JSON itself, use \n. If you are writing JSON text inside another language string literal, you often need \\n so the host language produces JSON text that contains \n.

// JSON file on disk
{"message":"First line\nSecond line"}

// JavaScript source code containing that JSON text
const jsonText = '{"message":"First line\\nSecond line"}';

3. CRLF vs LF differences

JSON can represent either style. Use \n for the most common cross-platform form, or \r\n if you need to preserve Windows line endings exactly. When line ending differences are not meaningful, normalize input before serializing.

// Normalize Windows CRLF and legacy CR to LF
const normalizedText = textInput.replace(/\r\n|\r/g, "\n");

4. The UI prints \n instead of a real new line

This usually means the app is showing the serialized JSON text rather than the parsed string. Parse first, then render the string value. In HTML or React, a safe display pattern is to preserve whitespace with CSS instead of injecting <br> tags into raw text.

• Web UI: use white-space: pre-wrap when you want line breaks to remain visible.
• API debugging: inspect the parsed object, not just the raw response body string.
• Logs: remember many consoles escape characters when they stringify nested objects.

What about JSON5 or other extensions?

If you have seen examples of multi-line strings that appear to work without standard JSON escaping, they are often using JSON5 or another extension. JSON5 allows strings to span multiple lines by escaping the newline, but that is not valid standard JSON and should only be used when every parser in your toolchain explicitly supports JSON5.

Best practices

• Use a JSON serializer instead of manual string concatenation.
• Use \n for ordinary line breaks and reserve \r\n for exact CRLF preservation.
• Normalize line endings before serializing if your application does not care about platform-specific style.
• When debugging, check whether you are looking at raw JSON text or the parsed string value.
• Validate copied or generated JSON with a formatter before shipping it to clients or APIs.

Bottom line

JSON does not have raw multi-line string literals. To add a line break in JSON, store it as \n or \r\n, and let your JSON library handle escaping whenever possible. Once you separate JSON text from the parsed string value, most line break problems become straightforward to diagnose and fix.