Turning Raw Text into JSON

Why text needs escaping to become JSON

JSON strings live between double quotes, which means any double quote inside the content must be escaped as backslash-quote or the parser reads it as the string's end. Backslashes themselves need doubling. Newlines and tabs cannot appear raw inside a JSON string at all — they become the escape sequences backslash-n and backslash-t. These are not style rules; violating them produces a parse error at the exact offending character. Conversion is the reliable way to apply all of them at once.

The control-character trap

Beyond visible characters, JSON forbids unescaped control characters (the range below space). Pasted content from terminals, logs, and rich editors frequently carries them invisibly. A payload that looks perfect in a text view fails strict parsers on the hidden byte — and the error message points at a position that appears blank. Converting through a proper encoder strips or escapes the full control range, which is the quiet reason to use tooling instead of hand-wrapping quotes.

Structuring: from flat text to useful shapes

Raw text becomes JSON in several standard shapes: a single string value; an array of lines; an object with named fields extracted from key: value formatted text. The choice depends on the consumer — a log viewer wants an array of entries, a config wants a keyed object, a simple transport wants one string. The structuring decision is a design decision about the reader; make it deliberately rather than defaulting to the whole blob.

Key-value text: the semi-structured middle

Much real-world text is almost structured: 'name: value' lines, email headers, environment dumps. Parsing these to JSON objects turns greppable text into queryable data. The edge cases define the quality: lines without colons, values containing colons, duplicate keys, and empty values. A conversion worth trusting handles each explicitly — typically by keeping everything after the first colon as the value and preserving duplicates in arrays.

Validation: the step that proves the conversion

The output of a text-to-JSON conversion must parse. Feeding the result through a JSON parser is the only proof that escaping was complete and structure balanced — 'it looks right' fails regularly on long inputs where one unescaped quote hides in the middle. Round-trip checking goes further: parse, re-serialize, and compare against expectations. For payloads bound for APIs, validation locally is the difference between a fix and a production error report.

Unicode: escapes versus raw characters

JSON permits non-ASCII characters either raw (UTF-8) or as backslash-uXXXX escapes — both valid, both equivalent after parsing. Raw UTF-8 reads better for humans; escaped form travels safely through systems that mangle encoding. The choice is transport-dependent: keep accented characters raw for human-readable configs, prefer escapes when the pipeline has a history of encoding damage. Either way, the decoded values must be identical.

Building payloads for APIs

The common workflow: compose a message or body in a text area, convert to a JSON string field, embed in the request shape. The failure to avoid is double-conversion — escaping an already-escaped string, producing double backslashes that survive as literal characters after one parse. The invariant: exactly one layer of JSON escaping between your content and the wire. Count backslash sequences in the final payload; double layers mean double conversion.

When CSV-ish and line data should be arrays

Line-oriented text converts naturally to JSON arrays, and arrays preserve order plus allow per-element processing downstream. The discipline: one element per logical line, empty lines skipped or preserved deliberately (they mean different things in prose versus data), and trailing newline handled consistently. Consumers that split strings themselves reproduce this logic inconsistently — delivering the array moves the parsing to one well-tested place.

Local conversion keeps sensitive payloads local

Text being structured often contains the sensitive part — user messages, internal notes, log excerpts. Browser-side conversion builds the JSON in place with nothing transmitted, and the validated result copies straight into the request. For payload preparation work, that locality removes the reason to avoid web tooling entirely.

JSON Lines: one object per line for streaming data

When text arrives or departs as a stream — logs, export feeds, bulk imports — the JSON Lines convention dominates: one complete JSON object per line, no wrapping array. The format's payoff is incremental parsing: consumers process each line independently, so a corrupt line fails alone and streaming never waits for the full payload. Converting line-oriented text into this shape means one object per source line plus the newline discipline — trailing newline included. The common error is wrapping the lines in a top-level array, which converts a streamable file back into a monolith and breaks the tooling that expected one object per line.

Nesting from indentation: converting outlined text

Indented text — outlines, YAML-ish notes, directory listings — encodes hierarchy that flat conversion throws away. The structured approach: treat indentation depth as nesting level, each line becoming a key or list element under its less-indented parent. The edge cases decide quality: inconsistent indent steps (mixed tabs and spaces need normalization first), siblings at mixed depths, and content lines under content lines. When the outline is regular, the conversion produces genuinely useful nested objects; when it is not, normalize the indentation before converting, because structural conversion faithfully reproduces whatever hierarchy the whitespace claims.

Turning loose text into valid JSON deliberately

Text-to-JSON work splits into two problems with different failure modes. Structuring unstructured text — inventing keys, choosing nesting, deciding what is a list — is a modeling decision where the mistakes are semantic: a flat structure where the data is hierarchical, or keys named for today's source that will not fit tomorrow's. Validation failures, on the other hand, are syntactic and mechanical: missing quotes around keys, trailing commas, unescaped newlines inside strings. A good workflow makes the modeling decision explicitly first, then lets tooling enforce the syntax.

The escaping step is the one everyone underestimates. Any string value can contain characters JSON forbids unescaped: double quotes, backslashes, control characters, and raw newlines. Text scraped from web pages or pasted from documents routinely contains all four. Hand-building JSON by string concatenation is how injection-flavored bugs enter systems — a quote inside a value closes it early and the rest of the text becomes syntax. Building JSON through a proper encoder eliminates the entire class, which is why every language's JSON library exists.

After generating, verify with the strictest consumer you can. A payload that parses in a lenient browser console can still fail a schema validator, an API contract check, or a database loader with UTF-8 enforcement. Parsing success means well-formed; only downstream acceptance means fit for purpose.

Common mistakes with this tool

• Hand-wrapping quotes and missing interior quotes or backslashes.
• Leaving raw newlines inside JSON strings.
• Double-escaping already-converted strings.
• Shipping converted payloads without running them through a parser.

Frequently asked questions