← Back to Blog

JSON, Base64, and the Developer Utilities You Use Every Day — Explained

FundamentalsJuly 7, 2026 · By Duc Nguyen · 13 min read

JSON and Base64 are two of the most frequently used formats in software development, and two of the least understood. Most developers reach for them daily — formatting an API payload, encoding a token, debugging a response — without a clear mental model of what each one actually is. That gap is where the bugs live: mangled encodings, silent data corruption, tokens that fail validation for reasons no one can explain. Let's make these formats concrete, so the next time something breaks you know exactly where to look.

JSON: a serialization format, not a file format

JSON (JavaScript Object Notation) is a way to represent structured data as text. That's it. It describes objects, arrays, strings, numbers, booleans, and null, using a syntax borrowed from JavaScript literals. It became ubiquitous because it's simple, human-readable, and parses cleanly in almost every language.

The key insight is that JSON is a serialization format — its job is to turn in-memory data into a string you can transmit or store, and back again. It is not a programming language, it has no comments, no trailing commas, no unquoted keys, and no functions. A surprising amount of "my JSON is broken" comes from treating it like source code rather than a strict interchange format.

Valid JSON, plainly

{
  "name": "Duc",
  "tools": 67,
  "free": true,
  "team": null
}

Keys are always double-quoted strings. Strings use double quotes, not single. Numbers are unquoted. These constraints aren't stylistic — a parser will reject anything that deviates.

The common JSON mistakes

The number of hours lost to these five mistakes is staggering, and it's why a JSON formatter and validator is one of the most-used developer tools. Paste the payload, see where it breaks, fix the line.

Tip: when JSON fails to parse, the error usually points to the character right after the problem, not the problem itself. If the parser complains about a closing brace, look at the comma or quote on the preceding line.

Base64: encoding for transport, not encryption

Base64 is where the most dangerous misconception lives. Base64 is an encoding: it converts arbitrary binary data into a string of ASCII characters, so that data can travel through systems that only handle text safely (email, JSON fields, URLs, HTTP headers). It is not encryption. Base64-encoded data is trivially reversible — anyone can decode it. Treating Base64 as a security measure is a serious, and common, mistake.

The way it works: Base64 takes every three bytes of input and represents them as four characters drawn from a 64-character alphabet (A–Z, a–z, 0–9, +, and /, with = as padding). Because the output uses only printable ASCII, it survives transmission through text-only channels without corruption. The trade-off is size — Base64 output is about 33% larger than the input.

When to use Base64

When not to use Base64

How they fit together

JSON and Base64 are often used together because they solve complementary problems. JSON is great for structured text but can't natively hold arbitrary binary data — you can't drop raw image bytes into a JSON string safely. Base64 lets you encode that binary as text, which then fits cleanly inside a JSON string field. The pattern is common in APIs that return files inline:

{
  "filename": "report.pdf",
  "mime": "application/pdf",
  "data": "JVBERi0xLjQKJ..."
}

The data field is Base64-encoded binary, sitting safely inside a JSON structure. The receiver decodes it back to bytes. This works, but remember the cost: that field is a third larger than the raw file, and the JSON payload carries it all in memory during parsing.

The UTF-8 trap

Here's a subtle bug that bites regularly. JavaScript's btoa() — the standard Base64 encoder — only handles Latin-1 characters. Pass it a string with an emoji or accented character, and it throws InvalidCharacterError. The reason is that btoa() treats each character as one byte, but UTF-8 characters outside Latin-1 are multi-byte.

The correct approach is to encode the string to UTF-8 bytes first, then Base64-encode those bytes:

// Safe Base64 for any Unicode string
function encode(str) {
  const bytes = new TextEncoder().encode(str);
  let binary = "";
  bytes.forEach(b => binary += String.fromCharCode(b));
  return btoa(binary);
}

This is exactly the kind of detail that makes a dedicated tool valuable — a good Base64 encoder handles UTF-8 correctly without making you remember the workaround. The same trap exists in reverse on decode, where naively decoding Base64 to a string can mangle multi-byte characters.

URL encoding, the third sibling

While we're here: URL encoding (percent-encoding) is often confused with Base64, but it solves a different problem. URL encoding makes a string safe to put inside a URL by replacing reserved or non-ASCII characters with %-prefixed hex codes — a space becomes %20, an ampersand becomes %26. You use it when embedding arbitrary text in a query parameter, not when transporting binary. Confusing the two produces URLs that either break or, worse, silently do something unintended.

Why these utilities deserve their own tools

None of these formats is conceptually hard, but each has enough sharp edges — strict parsing rules, encoding traps, size trade-offs — that a reliable utility saves real time. The reason I built formatters and encoders as client-side tools is precisely that you shouldn't have to paste sensitive API keys or production payloads into a random server-side converter to debug them. A tool that formats your JSON or decodes your Base64 entirely in your browser keeps that data private while it fixes the immediate problem. (I wrote about why that architectural choice matters in why client-side tools protect your privacy.)

The mental model to keep

If you take one thing from this: JSON is for structure, Base64 is for transport, URL encoding is for URLs, and none of them is for security. Know which problem you're solving, reach for the format that solves that problem, and you'll avoid the silent failures that make these formats feel finicky. The utilities are there to handle the fiddly details; understanding what each one is for is what keeps you out of trouble in the first place.

Real-world debugging scenarios

Here are three situations where understanding these formats saved hours:

Performance considerations

When working with these formats at scale, a few performance notes matter. JSON.parse() and JSON.stringify() are highly optimized in modern engines — they're often faster than manual parsing. But they're still synchronous and block the main thread. For very large payloads (10 MB+), consider streaming parsers or Web Workers. Base64 encoding in the browser via btoa() is also synchronous; the UTF-8-safe version above adds overhead. For large binary blobs, the FileReader API with readAsDataURL() can be more efficient since it offloads to the browser's native implementation.

Security implications summary

To recap the security surface: JSON injection attacks happen when untrusted data is concatenated into JSON strings without proper escaping — always use a serializer. Base64 provides zero confidentiality; treat encoded data as plaintext. URL encoding prevents injection into query strings but doesn't protect against XSS in HTML contexts — use contextual escaping for that. Each format solves one problem; layering them doesn't compose security.

← All articles ← Back to home
Home About Blog Contact Privacy Terms GitHub