How to format and validate a JSON document

⌚ About 2 min read

Validate JSON syntax, make it readable, and locate errors before an import or API call.

Before you start

Work on a copy or a controlled test when the change can affect production. Keep timestamps, screenshots and the previous configuration so the result can be compared.

Step by step

Copy only the JSON to inspect and remove secrets or access tokens.
Test it with the BAOI JSON Formatter & Validator.
Fix the first reported issue: comma, quote, brace, or unexpected type.
Validate again and compare the structure with the application or API schema.
Keep a minified version only when the target system requires it.

Validation

Repeat the original test after the change and confirm that the expected service works without creating a new regression. Document the final state.

Technical deep dive

JSON / JWT: valid syntax does not mean trusted data

Technical checkpoints

JSON requires double quotes for strings/keys and standard JSON allows neither comments nor trailing commas.
A JWT is three base64url segments header.payload.signature; decoding header/payload does not verify the signature.
Claims exp, nbf, iss and aud must be interpreted in the context of issuer and signing key.

JWT example

Decode locally for inspection only; never paste a real token into a third-party service.

header.payload.signature
# Base64URL != standard Base64: -/_ and padding can differ

Topic-specific pitfalls

Well-formatted JSON can still be semantically invalid for the target API.
Seeing alg=none or an unexpected algorithm without checking validation policy is a security warning.

How to validate

JSON is validated by the parser and, when available, by the expected schema.
A JWT is considered valid only after cryptographic verification plus issuer, audience and temporal claims checks.

Operational context

JSON validation should distinguish syntax validity from schema or business validity. Format the document locally, parse it with a strict JSON parser, then apply any required JSON Schema or application-specific constraints.

Step-by-step checks

Work on a copy and keep sensitive JSON local when it can contain tokens, credentials or personal data.
Parse the original document before reformatting so a formatter does not hide where the syntax problem occurred.
Check quotes, commas, brackets, escaping, number syntax and encoding; remember that comments and trailing commas are not valid standard JSON.
If the consuming system has a schema, validate types, required properties, enums and nested structures after syntax parsing succeeds.

Useful verification commands

Use commands only on systems you administer and capture the read-only output before making a configuration change.

python -m json.tool file.json

jq empty file.json

How to validate the result

At least two independent local parsers should accept the JSON, and the target application/schema validator should accept the resulting structure without coercing unexpected values.

Evidence to keep

Keep the parser error position, a sanitized failing fragment if needed, the schema/version used and the successful validation output.

Frequently asked question

Does pretty-printing prove that JSON is valid for my application?

It proves only that a parser accepted the syntax. Your application can still reject valid JSON because required fields, types or domain rules are wrong.

Related BAOI resources: IT tools · procedures · IT dictionary.