JSON has become the lingua franca of data exchange, but working with complex JSON structures requires more than a viewer. This guide covers four essential JSON tools: JSONPath for querying nested data, JSON Schema for validation, JSON Diff for comparing documents, and JSON-to-CSV conversion for data analysis.
Whether you're debugging API responses, validating request payloads, or preparing JSON data for spreadsheet analysis, these tools will significantly improve your workflow.
JSONPath: Querying Nested JSON
JSONPath is to JSON what XPath is to XML -- a query language for extracting values from deeply nested structures. It was created by Stefan Goessner and is now standardized as RFC 9535.
Basic JSONPath syntax:
{
"store": {
"books": [
{ "title": "JavaScript", "price": 29.99, "category": "dev" },
{ "title": "Python", "price": 19.99, "category": "dev" },
{ "title": "Cooking", "price": 15.99, "category": "lifestyle" }
],
"owner": "Alice"
}
}$.store.books[0].title => "JavaScript"
$.store.books[*].title => ["JavaScript", "Python", "Cooking"]
$.store.books[0:2].title => ["JavaScript", "Python"] (slice)
$.store.books[-1].title => "Cooking" (last element)
$.store.books[?(@.price < 25)] => books with price < 25 (filter syntax varies by implementation)
$.store..price => all price values (recursive descent)
$..title => all title values anywhereUsing JSONPath in JavaScript:
// Using jsonpath-plus library:
import { JSONPath } from 'jsonpath-plus';
const data = { /* your JSON */ };
const titles = JSONPath({ path: '$.store.books[*].title', json: data });
// => ['JavaScript', 'Python', 'Cooking']The examples above use the filter syntax supported by this guide's JSONPath tool. JSONPath implementations can differ in expression details, so check the syntax supported by your library or evaluator.
Using JSONPath in Python:
from jsonpath_ng import parse
expr = parse('$.store.books[*].title')
matches = [m.value for m in expr.find(data)]JSON Schema: Validating Structure and Types
JSON Schema (jsonschema.org) defines the structure, types, and constraints that a JSON document must follow. It's the standard for API request/response validation.
Basic schema example:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["id", "name", "email"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"tags": {
"type": "array",
"items": { "type": "string" },
"uniqueItems": true
}
},
"additionalProperties": false
}Try this schema with the JSON Schema Validator. Keep the draft declared in $schema aligned with the validator and schema vocabulary used by your project.
Common validation keywords:
- type: string, number, integer, boolean, array, object, null
- required: array of required property names
- minimum/maximum: number bounds
- minLength/maxLength: string length bounds
- pattern: regex pattern for strings
- enum: allowed values list
- $ref: reference to another schema (for reuse)
- oneOf/anyOf/allOf: composition operators
Validation in Node.js:
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
const ajv = new Ajv();
addFormats(ajv);
const validate = ajv.compile(schema);
const valid = validate(data);
if (!valid) console.log(validate.errors);JSON Diff: Comparing JSON Documents
JSON Diff tools show structural differences between two JSON documents, which is invaluable for debugging API version changes, configuration drift, and data migration verification.
Compare before and after payloads with the JSON Diff tool. A visual diff helps diagnosis; if another system needs to apply a change, use a defined patch format such as RFC 6902.
Types of differences:
- Added: a key exists in the new version but not the old
- Removed: a key exists in the old version but not the new
- Changed: a key exists in both but the value differs
- Type changed: the value type changed (string to number, etc.)
- Array reordering: elements exist in both but in different positions
RFC 6902 JSON Patch format -- a standardized diff format:
[
{ "op": "replace", "path": "/name", "value": "Alice Smith" },
{ "op": "add", "path": "/phone", "value": "+1-555-0100" },
{ "op": "remove", "path": "/deprecated_field" }
]Operations: add, remove, replace, move, copy, test
Applying JSON Patch in JavaScript:
import { applyPatch } from 'fast-json-patch';
const original = { name: "Alice", age: 30 };
const patch = [
{ op: "replace", path: "/name", value: "Alice Smith" },
{ op: "add", path: "/email", value: "[email protected]" }
];
const result = applyPatch(original, patch).newDocument;
// => { name: "Alice Smith", age: 30, email: "[email protected]" }JSON to CSV: Converting for Data Analysis
Spreadsheet tools like Excel and Google Sheets work natively with CSV, making JSON-to-CSV conversion useful for data analysis. Try a sample with the JSON to CSV tool and inspect how nested objects and arrays are represented before exporting a full dataset.
Simple array of objects converts naturally to CSV:
[
{ "name": "Alice", "age": 30, "city": "London" },
{ "name": "Bob", "age": 25, "city": "Paris" },
{ "name": "Carol", "age": 35, "city": "Berlin" }
]Becomes:
name,age,city
Alice,30,London
Bob,25,Paris
Carol,35,BerlinComplex nested objects require flattening:
[
{
"id": 1,
"user": { "name": "Alice", "email": "[email protected]" },
"order": { "total": 99.50, "items": 3 }
}
]After flattening:
id,user.name,user.email,order.total,order.items
1,Alice,[email protected],99.50,3Handling arrays in cells: arrays can be joined with a delimiter (e.g., |) or each element can become a separate column.
CSV with proper escaping:
- Values containing commas must be quoted: "Smith, John"
- Values containing double quotes must escape them: "He said ""hello"""
- Newlines in values require quoting the entire value
Practical Workflow: API Debugging with JSON Tools
Example: an API changes a user's avatar field
Old response:
{ "data": { "users": [{ "id": 42, "profile": { "avatar_url": "/img/u42.png" } }] } }New response:
{ "data": { "users": [{ "id": 42, "profile": { "avatar": "/img/u42.png" } }] } }1. Compare both payloads in JSON Diff; the changed path shows profile.avatar_url removed and profile.avatar added.
2. Query $.data.users[*].profile.avatar_url in JSONPath to confirm the old field has no matches. This tool uses jsonpath-plus compatible syntax.
3. Validate the new payload with JSON Schema Validator. Add a required-field check if clients depend on avatar.
4. For bulk review, convert the array with JSON to CSV and inspect the resulting columns.
General workflow for other API changes
1. Capture the old and new API responses
2. Use JSON Diff to identify exactly what changed
3. Use JSONPath to extract the specific field that broke your code:
```
$.data.users[*].profile.avatar_url
```
4. Check JSON Schema to verify the new response still conforms to your expected contract
5. Export to CSV for bulk review if the response contains large arrays
Scenario: Validating incoming webhook data
1. Define a JSON Schema for expected webhook payload
2. Validate every incoming request against the schema
3. Reject (HTTP 400) requests that fail validation
4. Use JSON Schema's $ref keyword to reference reusable definitions (JSONPath is a separate query language).
For syntax details, see the JSONPath standard (RFC 9535), JSON Patch (RFC 6902), JSON Schema getting started guide, and CSV common format (RFC 4180). This combination of tools transforms raw JSON manipulation into systematic, reliable data engineering.