DEV Community

Tsan-Huang Chen
Tsan-Huang Chen

Posted on

Reliable JSON formatting and conversion from raw payload to review-ready output

#data #productivity #softwaredevelopment #tools

Disclosure: I build YourConvertor, the browser-based tool used in this walkthrough. The workflow below also applies to other JSON formatters.

A payload can be valid JSON yet hard to review when compressed into one line. The useful sequence is: validate syntax, format for readability, check meaning, then convert only if a downstream consumer needs another format.

1. Start with a reproducible example 

{"order":{"id":"a1","items":[{"sku":"X-1","qty":2},{"sku":"Y-9","qty":1}],"meta":{"source":"web","notes":"  urgent  "}},"ok":true,"total":42.5}
Enter fullscreen mode Exit fullscreen mode

Paste this sample into YourConvertor JSON Formatter. Run the formatter and inspect the structure. With two-space indentation, the same data looks like this:

{
  "order": {
    "id": "a1",
    "items": [
      {
        "sku": "X-1",
        "qty": 2
      },
      {
        "sku": "Y-9",
        "qty": 1
      }
    ],
    "meta": {
      "source": "web",
      "notes": "  urgent  "
    }
  },
  "ok": true,
  "total": 42.5
}
Enter fullscreen mode Exit fullscreen mode

Notice that the spaces inside " urgent " remain. Formatting whitespace around JSON tokens is not the same as trimming string values.

2. Fix syntax errors before changing the data

This example is invalid because JSON does not allow trailing commas:

{"id": "a1", "qty": 2,}
Enter fullscreen mode Exit fullscreen mode

Corrected:

{"id": "a1", "qty": 2}
Enter fullscreen mode Exit fullscreen mode

Other common problems include single-quoted property names, comments copied from JavaScript, and literal unescaped line breaks inside strings. JSON requires double-quoted names and strings. Tabs between tokens and properly escaped characters inside strings are valid; do not remove them indiscriminately.

3. Separate syntax from meaning

Both of these values are valid JSON, but they mean different things to consumers:

{"qty": 2}
Enter fullscreen mode Exit fullscreen mode 
{"qty": "2"}
Enter fullscreen mode Exit fullscreen mode

A successful parse does not prove that a payload satisfies your API schema. Check required fields, value types, and business rules separately. Keep identifiers with leading zeros as strings when that is what the schema requires.

4. Decide what one CSV row represents

Nested JSON does not have a single universally correct CSV representation. Consider this order:

{
  "id": "o-1001",
  "customer": "Ari",
  "items": [
    { "sku": "X-1", "qty": 2, "price": 12.5 },
    { "sku": "Y-9", "qty": 1, "price": 17.5 }
  ]
}
Enter fullscreen mode Exit fullscreen mode

If each row represents one item, an illustrative mapping is:

order_id,customer,item_sku,qty,price
"o-1001","Ari","X-1",2,12.5
"o-1001","Ari","Y-9",1,17.5
Enter fullscreen mode Exit fullscreen mode

This mapping repeats the order fields for each item. It is a transformation design, not a claim that every converter automatically produces these columns. Flatten the records explicitly or configure a converter that supports your required mapping.

For JSON-to-XML conversion, also decide how arrays, nulls, and the root element should be represented. Preserve the original JSON because a round trip may not preserve every type or structural choice.

5. Use a short review checklist

  • Does the input parse without syntax errors?
  • Are string, number, boolean, and null values still the intended types?
  • Are spaces inside strings preserved where meaningful?
  • Does each converted row represent the intended entity?
  • Are nested items retained rather than silently dropped?
  • Have you kept the original payload for comparison?

Frequently asked questions

Does formatting validate my API schema?

No. Syntax validation checks whether text is JSON. Schema validation checks constraints such as required fields and allowed types. Business rules may require additional checks.

Does formatting sort keys or clean values?

Not inherently. Sorting keys and normalizing values are separate operations. Agree on those rules before using them in diffs or reviews.

Can I safely paste production credentials?

Use synthetic examples when possible. Browser-side processing does not remove risks from extensions, shared devices, or accidentally sharing the resulting text. Never include secrets in bug reports or public examples.

What should I try first?

Use the sample above in YourConvertor JSON Formatter, then compare the formatted output against the original values. Readability should improve without changing the meaning of the data.

Top comments (0)