JSON Explained: How to Format, Validate and Convert It

The building blocks of JSON

JSON is defined by the ECMA-404 standard and RFC 8259, and the whole grammar fits on a single page. There are only six kinds of values: strings, numbers, booleans, null, objects and arrays.

An object is an unordered set of name and value pairs wrapped in curly braces, with each name written as a string in double quotes, followed by a colon and a value, and pairs separated by commas. An array is an ordered list of values wrapped in square brackets and separated by commas. Objects and arrays can be nested inside each other to any depth, which is how JSON represents complex records.

Strings must use double quotes. Special characters inside a string are escaped with a backslash, for example a backslash and n for a new line, a backslash and a double quote for a literal quotation mark, or a backslash, u and four hexadecimal digits for any Unicode character. Numbers are written in decimal, may be negative, may include a fraction and an exponent, and may not have leading zeros. The literals true, false and null are always lowercase. Text exchanged between systems should be encoded as UTF-8.

For example, a user record might be written as an object with the name id set to 1042, name set to the string Ana Torres, email set to ana@example.com, active set to true, roles set to an array containing editor and billing, and manager set to null. That one structure uses every JSON value type except a nested object.

The most common JSON errors

Most invalid JSON comes from habits carried over from JavaScript or hand editing. Trailing commas are the most frequent culprit: a comma after the last item in an array or object is allowed in modern JavaScript but is a syntax error in JSON. Single quotes are another. JavaScript accepts single-quoted strings, but JSON requires double quotes for both names and string values.

Unquoted property names fail for the same reason. Comments are not part of JSON at all, so a line starting with two slashes will break parsing, even though some configuration tools accept a relaxed variant that allows them. The values undefined, NaN and Infinity do not exist in JSON. Numbers with leading zeros, such as 007, are invalid, which matters for things like ZIP codes and phone numbers that should be stored as strings anyway.

Other problems are harder to see: a raw line break or tab inside a string, which must be escaped; a stray byte order mark at the start of a file; mismatched brackets in deeply nested data; or two separate JSON documents pasted into one file. When a parser reports an error, the position it gives is where it gave up, which is sometimes a little after the real mistake, so look at the characters just before the reported spot.

Formatting versus minifying

Whitespace between tokens has no meaning in JSON, so the same data can be written in very different shapes. Formatting, also called pretty-printing, puts each value on its own line and indents nested levels, usually with two or four spaces. It is how you want JSON when reading an API response, reviewing a configuration change or debugging.

Minifying removes every unnecessary space and line break. Taking the user record above as a worked example, the version pretty-printed with two-space indentation is 153 bytes, while the minified version is 115 bytes. That saves 38 bytes, about 25 percent, with no change to the data. On a single record that is trivial, but for large API responses sent millions of times the difference adds up. In practice, HTTP compression such as gzip or Brotli removes much of the repetitive whitespace too, so minifying matters most for stored files, embedded data and situations where compression is not applied.

A good rule is to keep JSON formatted in source control, where people need to read diffs, and minify it when it is sent over the network or embedded in a page.

Converting CSV to JSON

Spreadsheets and databases often export CSV, a plain text table where each line is a row and values are separated by commas, semicolons or tabs. Converting CSV to JSON usually means treating the first row as headers and turning every following row into an object whose property names are those headers. A three-column file with headers id, name and city becomes an array of objects, each with id, name and city properties.

Several details deserve attention. Values containing the delimiter must be wrapped in double quotes, and a literal double quote inside a quoted value is written as two double quotes. Every row should have the same number of cells as the header row. Header names should be unique, since duplicates would overwrite each other in the resulting objects. Finally, CSV has no data types, so every value starts life as text. If you need numbers or booleans in the JSON, convert those fields deliberately after import rather than assuming they were detected, and keep identifiers such as ZIP codes as strings so leading zeros survive.

Generating TypeScript types from JSON

When code consumes JSON from an API, TypeScript interfaces describe what shape the data should have, so editors can autocomplete property names and the compiler can catch mistakes like misspelled fields. Writing those interfaces by hand for a large response is tedious and error-prone.

Generating them from a real sample is faster. Each JSON object becomes an interface, nested objects become their own named interfaces, arrays become typed arrays, and primitive values map to string, number and boolean. For the user record, the result is an interface with id as a number, name and email as strings, active as a boolean and roles as an array of strings.

Remember that a sample only shows what was present in that one response. A field that happened to be null, or missing entirely, tells the generator little about its real type, so review the output against the API's documentation and adjust optional fields and unions where needed.

Base64 inside JSON APIs

JSON is a text format and cannot hold raw binary data such as images, PDFs or cryptographic keys. The usual solution is Base64, which represents any sequence of bytes using 64 safe text characters. Every 3 bytes of input become 4 characters of output, so Base64 adds about 33 percent overhead. For example, the 3-byte text Hi! encodes to SGkh, and a 300,000 byte file becomes a 400,000 character string.

You will see Base64 in many places around JSON: file uploads embedded in a request body, data URLs for small images, the HTTP Basic authentication header, and JSON Web Tokens, whose sections are Base64url-encoded JSON. Base64url is a variant that replaces plus and slash with hyphen and underscore and often drops the trailing equals padding, so the result is safe in URLs and file names. Keep in mind that Base64 is an encoding, not encryption. Anyone can decode it, so never treat a Base64 string as a way to hide secrets. For large files, uploading the binary separately is usually more efficient than inflating a JSON payload by a third.

Working with JSON in ToolWorld tools

The ToolWorld JSON Formatter / Validator pretty-prints JSON with two- or four-space indentation, minifies it, and shows the parser's error message when the input is invalid, which makes trailing commas and stray quotes quick to find. You can paste text or open a JSON file and then copy or download the result.

The CSV to JSON converter accepts pasted CSV or an uploaded file, detects the delimiter automatically or lets you choose one, uses the first row as headers, handles quoted fields, and reports clear errors for empty or duplicate headers and rows with the wrong number of cells. Values come through as strings, matching the CSV source.

The JSON to TypeScript tool converts a sample into exported interfaces with a root name you choose, creates separate interfaces for nested objects, marks nullable fields as optional and lets you copy or download a .ts file. For binary data, the Base64 Encoder / Decoder converts text or files to and from Base64, with a URL-safe option for Base64url. All four run in your browser, so data you paste in stays on your device while you work.