What JSON is designed to do
JSON, or JavaScript Object Notation, is a text format for representing objects, arrays, values, and relationships. It is common in APIs, configuration files, browser storage, logs, exports, and small data exchanges because people can read it and programs can parse it without much overhead.
The format has a small vocabulary: objects use braces, arrays use brackets, keys and text values use double quotes, and values can be strings, numbers, booleans, null, objects, or arrays. Because the rules are limited, a valid document can move between many languages and systems.
Format first, then interpret
When JSON arrives on one long line, do not try to understand it all at once. Run it through a formatter so nesting, repeated structures, and long values become visible. Indentation does not change the data; it only gives your eyes a reliable map of the document.
A formatted response makes it easier to compare two payloads, spot an empty value, find a missing field, or copy one object without accidentally selecting a neighboring item. It is especially helpful when a browser network panel or log has collapsed the structure into a single unreadable line.
Read parser errors as a location clue
A validator usually reports an error near the place where parsing became impossible. The real mistake may be one character earlier: a missing comma can make the next key look unexpected, and a missing closing bracket can make the parser complain at the very end of the file.
Start at the reported line and column, then inspect the previous key, value, comma, and bracket. Use the formatted version to count the nesting level. Fix one structural problem at a time and run the validator again instead of making a long series of guesses.
Fix the common syntax mistakes
The most frequent problems are single quotes around keys, unquoted keys, trailing commas, missing commas between properties, and comments copied from a JavaScript file. Standard JSON does not allow comments, and it requires double quotes for property names and string values.
Another common error is mixing a JSON object with a JavaScript object literal. JavaScript may accept undefined, functions, or special numeric values in a particular context, but those values are not valid JSON. If the data must travel through an API, keep it within the stricter JSON rules.
Understand objects and arrays
An object is a collection of named properties, such as a user with a name, email, and role. An array is an ordered list, such as several users or several tags. Real API responses often combine both: an outer object contains a results array, and each item in that array is another object.
Follow the shape from the outside in. Ask what the top-level value is, which keys are always present, which fields can be null, and whether an array can be empty. These questions matter more than the visual indentation because they determine how your code should handle real responses.
Separate formatting from security
A formatter can make data easier to read, but it does not make sensitive data safe. JSON may contain access tokens, personal information, private addresses, internal URLs, or credentials. Before pasting a payload into a third-party service, remove secrets or use a local tool that keeps the data on your machine.
Base64 is not encryption, and formatting is not protection. If you need to share a sample in a bug report, replace identifying values with realistic placeholders and keep the original response in an approved private location. A clean example is often more useful than an unredacted production dump.
Make API debugging more methodical
When an API response is wrong, record the request method, endpoint, status code, response headers, and a safe sample of the response. Then validate the body before deciding that the server returned the wrong business value. A syntax problem can make a good response look like an application failure.
Compare the expected schema with the actual fields. Check spelling and capitalization, because `userId` and `userid` are different keys. Check whether a value changed type, such as a number becoming a string, and whether the response is an error object instead of the result object your code normally receives.
Keep JSON readable in a project
Use one formatting convention across a project and let an editor or formatter apply it consistently. Stable indentation creates smaller, clearer diffs, so reviewers can see what data changed instead of reviewing a whole file as if every line were new.
Validate configuration during a build or deployment when the file controls a critical service. For API contracts, document required and optional fields, example values, nullability, and error responses. A formatter helps with presentation, but a shared contract prevents two teams from making different assumptions about the same data.
A simple repair routine
When a document fails, copy a safe version, format it if possible, and read the first error from the top. Inspect the surrounding punctuation, then remove comments, replace single quotes, and check every opening delimiter has a matching closing delimiter. Re-run the validator after each focused change.
Once the document is valid, test the meaning as well as the syntax. Confirm required fields exist, arrays contain the expected item shape, and values are within the range your application accepts. Valid JSON can still describe the wrong thing, so parsing is the start of debugging rather than the finish.
Use examples that survive real data
A tiny example is useful for learning, but production responses often contain empty arrays, null fields, optional properties, and unexpected text. Include those cases in tests so your code does not work only for the neat sample shown in the documentation.
When you document a JSON response, show the smallest complete example and explain which fields are stable. If an object can grow over time, make clients ignore unknown fields rather than failing. That approach lets a service add useful information without breaking older consumers.
Validate before you deploy
A valid file can still fail when it is loaded in the wrong place or with the wrong encoding. Check that the application reads the file you edited, that environment-specific values are present, and that a deployment did not truncate or merge the content. Keep a small fixture in automated tests so an obvious syntax error is caught before it reaches production.
If a parser error appears only in one environment, compare the exact bytes and runtime versions instead of assuming the data changed. Look for a hidden character, a different escaping rule, or a server process reading an older cached copy. The formatter confirms the document itself; deployment checks confirm that the right document reached the right consumer.
Put this into practice
Use the free GigaTools toolkit
Run a check, review the result, and make one useful improvement at a time.
Quick answers
Frequently asked questions
Why does valid-looking JSON fail?
A missing comma, quote, or closing bracket can be hard to see in a compact response. Format the data and start at the reported line and column, then inspect the character immediately before it.
Can JSON contain comments?
Standard JSON does not support comments. Some configuration systems add their own extensions, but remove comments before sending data to a normal JSON parser.
Should I paste production JSON into an online tool?
Redact credentials and personal information first. For confidential data, use a trusted local formatter or an approved internal tool.