A JSON formatter can make a difficult API debugging session easier to read, but formatting alone does not prove that a payload is valid or suitable for your application. This guide provides a repeatable workflow for formatting and validating JSON, locating syntax errors, handling escaped characters and nested data, comparing payloads, and checking sensitive information before you paste anything into a browser-based tool.
Overview
JSON is designed to be readable by machines and reasonably readable by people, yet real API responses can become difficult to inspect when they arrive on one line, contain deeply nested objects, or include escaped strings. A JSON formatter, sometimes called a JSON pretty printer, adds indentation and line breaks so you can inspect the structure. A JSON validator or syntax checker goes a step further by determining whether the input follows JSON's grammar.
Those functions solve different problems. Formatting helps you see relationships between objects and arrays. Validation helps identify invalid punctuation, unsupported values, missing quotes, or incomplete input. Neither process confirms that the data has the right business meaning. A valid payload can still contain the wrong field name, an unexpected data type, a missing record, or a timestamp your application cannot parse.
For API debugging, use this sequence:
- Preserve the original response or request body.
- Check whether the content is actually JSON rather than HTML, plain text, or another format.
- Run the content through a JSON validator.
- Format the valid result for inspection.
- Compare it with a known-good payload or the API contract.
- Test the smallest useful correction in your client or request.
For a broader workflow covering inspection and transformation, see the JSON and API Debugging Toolkit. If your goal is to display records rather than diagnose a response, the guide to building a browser-based data viewer for JSON and CSV provides a useful next step.
Checklist by scenario
When JSON is difficult to read
- Copy the complete payload, including the first and last characters.
- Use a JSON formatter to add indentation and line breaks.
- Collapse large arrays or nested objects while locating the relevant branch.
- Check whether repeated objects use the same fields and data types.
- Keep the unformatted original available so whitespace changes are not mistaken for data changes.
Formatting is especially useful when inspecting dashboard responses, configuration files, webhook bodies, and nested objects returned by cloud services. Once the structure is visible, look for the path your application expects, such as data.items[0].id, rather than searching only for a familiar word.
When a validator reports a syntax error
- Read the reported line and column, but inspect the preceding character as well.
- Check for a missing comma between properties or array values.
- Check for an extra comma after the final property or item.
- Confirm that every property name is enclosed in double quotes.
- Confirm that strings use double quotes rather than single quotes.
- Verify that braces and brackets are paired and correctly nested.
- Replace unsupported values such as
undefined,NaN, or an unquoted placeholder with a JSON-compatible value.
Error locations are often symptoms rather than the original cause. For example, a missing comma may not be noticed until the parser reaches the next property. Start at the reported position, then scan backward to the previous comma, quote, bracket, or brace.
When an API response looks like JSON but will not parse
- Inspect the first character for an unexpected status message, markup, or logging prefix.
- Check the response status and content type in your browser's network panel.
- Look for an HTML error page returned by a proxy, gateway, or authentication layer.
- Check whether the response is wrapped in a string, such as a quoted JSON document inside another response.
- Confirm that compressed, encoded, or escaped content has been handled by the client before parsing.
A response can fail JSON parsing even when the service normally returns JSON. The actual response may be an authentication message, a rate-limit notice, a server error, or a truncated connection. Preserve the status code and headers alongside the body; the body alone may not explain the failure.
When comparing two payloads
- Format both documents using the same indentation and ordering rules.
- Compare types as well as values: a number, string, boolean, and null are not interchangeable.
- Check whether array order is meaningful before treating reordered items as a change.
- Separate expected volatile fields, such as request identifiers or timestamps, from meaningful differences.
- Compare the schema first, then investigate individual values.
A formatted view makes visual comparison easier, but it does not automatically understand whether two arrays are semantically equivalent. For large responses, use a structured comparison tool or a small script that can ignore approved fields.
What to double-check
Before deciding that an API is broken, work through this validation checklist:
- Syntax: Does the document parse as one complete JSON value?
- Root type: Does the API return an object, an array, or another allowed value?
- Required fields: Are the fields required by the client present?
- Data types: Are identifiers, amounts, dates, flags, and lists represented in the expected form?
- Nullability: Can a field be null, or must it always contain a value?
- Nested paths: Is the data located at the path used by the application?
- Encoding: Are escaped quotes, backslashes, Unicode characters, and line breaks represented correctly?
- Completeness: Is the response truncated or missing pagination information?
- Context: Do the status code, headers, and request parameters match the payload?
Pay particular attention to escaped content. A value such as "{'enabled':true}" is a string containing JSON, not a nested object until the application parses it a second time. Conversely, parsing every string as JSON can create errors when ordinary text happens to contain braces.
Privacy is another essential check. Do not paste access tokens, passwords, private customer records, session cookies, or production secrets into an online utility unless your organization's rules explicitly allow it and you understand how the tool handles input. When possible, remove or replace sensitive values, use a local workflow, or work with a minimal representative sample. A redacted payload should preserve the original structure and data types so that debugging remains meaningful.
Common mistakes
Confusing JavaScript objects with JSON
JavaScript object literals may use unquoted property names, single-quoted strings, comments, functions, or values such as undefined. Standard JSON is more restrictive. A snippet that works in a JavaScript file may fail in a JSON validator or when sent as an API body.
Fixing the displayed copy instead of the source
Manual edits in a formatted result are useful for testing a hypothesis, but they do not repair the service or application that produced the payload. Record the original input, identify the producing request or transformation, and make the durable change there.
Ignoring the response envelope
Applications often expect a path such as response.data.items while the service returns items at the root, or the reverse. The document can be perfectly valid and still cause an empty dashboard or undefined value. Check the contract and the client mapping together.
Assuming formatting changes the data
Whitespace outside strings generally affects presentation, not the parsed value. However, edits made while formatting can change content inside strings, alter escape sequences, or remove meaningful characters. Treat formatting as a viewing step and validate again after any edit.
When to revisit
Use this checklist whenever an integration breaks, an API response changes shape, or a dashboard starts showing empty, partial, or incorrectly typed data. Revisit it after changing authentication, request parameters, response transformations, pagination logic, or client-side type definitions. It is also useful before seasonal planning cycles or other periods when a dependable reporting workflow matters and upstream data may have changed.
When tools or workflows change, confirm that your chosen JSON formatter and validator still support the operations you need, including large-payload handling, structured comparison, redaction, and local or offline use where appropriate. Keep a small, sanitized known-good payload in your project documentation. It gives future debugging sessions a stable comparison point without exposing production data.
For a practical final pass, save the original response, validate the syntax, format the document, check the expected schema and paths, compare it with a known-good sample, and test the smallest reproducible request. If the issue involves dashboard performance after the data is correct, continue with the JavaScript data dashboard guide and the guide to caching dashboard queries.
