What is the difference between jq, JSONPath, and XPath?
jq is a JSON filter and transformation language. It can extract fields, restructure objects, filter arrays, compute values, and pipeline multiple operations together. It goes well beyond path selection — it is closer to a data-processing language for JSON.
JSONPath is a JSON selection language. It extracts values from JSON documents using path expressions. JSONPath is now formalized in RFC 9535. It is simpler than jq and commonly used in test automation frameworks and API tooling where you need to select specific values from a JSON response.
XPath is a language for navigating XML and HTML DOM structures. It uses axes (child, descendant, parent, attribute) to traverse document trees and select nodes. XPath is the standard query language for XML and is also used to query parsed HTML in testing and web scraping contexts.
They overlap in simple extraction tasks but are not interchangeable. jq and JSONPath work only with JSON. XPath works only with XML/HTML DOM trees. jq can transform data; JSONPath and XPath primarily select it.
When should I use jq vs JSONPath vs XPath?
Use jq when you need to map, transform, restructure, or pipeline-process JSON. If you need to extract fields and reshape them into a new object, filter arrays by complex conditions, or chain multiple operations, jq is the right tool.
Use JSONPath when you need simple field selection from JSON responses — especially in testing and API automation contexts where the toolchain already supports JSONPath (REST Assured, Postman, Karate, etc.).
Use XPath when the source document is XML or HTML. XPath is the native query language for DOM trees and is the only option among the three for navigating XML/HTML structures.
Query Rosetta Stone
A practical cross-reference for common extraction tasks. Note that jq and JSONPath use 0-based array indexing, while XPath positional predicates are effectively 1-based.
| Goal | jq | JSONPath | XPath |
|---|---|---|---|
| Root | . | $ | / |
| Get a child | .name | $.name | /root/name |
| First array item | .[0] | $[0] | //item[1] |
| Filter by value | .[] | select(.x > 5) | $[?(@.x > 5)] | //item[x > 5] |
| Recursive search | .. | .name? // empty | $..name | //name |
| Extract text / scalar | .field | $.field | //field/text() |
| Select attribute | n/a (JSON has no attributes) | n/a | //@id |
| Map to smaller object | .[] | {a: .x} | not supported | not supported |
Common query mistakes
Invalid payload vs invalid query. When something fails, the first step is confirming whether the payload itself is malformed (invalid JSON, broken XML) or whether the query syntax is the problem. The error decoder in this workbench separates the two.
Mode mismatch. Using jq or JSONPath on an XML payload, or XPath on raw JSON, produces confusing errors. The workbench detects this and shows a friendly explanation instead of a parser crash.
XPath namespace surprises. If your XML uses a default namespace (xmlns="..."), unprefixed XPath expressions will not match the elements you expect. You need to either use namespace prefixes in your XPath or use local-name() to ignore namespaces.
jq null iteration. The error cannot iterate over null means jq tried to use .[] or a similar iterator on a field that is null or missing. Use select(. != null) or the alternative operator // empty to handle missing fields.
JSONPath implementation differences. JSONPath behavior has historically varied between implementations. RFC 9535 standardizes the syntax, but older libraries may behave differently for edge cases like filter expressions and recursive descent. This tool uses jsonpath-plus, which aligns with the RFC.
XPath indexing. XPath positional predicates are effectively 1-based: //item[1] selects the first item, not the second. jq and JSONPath use 0-based indexing for arrays.
Why test queries locally before hardcoding them
Extraction queries embedded in scripts, CI pipelines, test suites, and API integrations are difficult to debug once deployed. A jq filter that works against the expected payload shape but fails on an edge case — a missing field, a null value, an unexpected array — can break a build or produce silent data loss.
Testing queries against real or realistic payloads in a local workbench before committing them catches these issues earlier. The shareable permalink feature also makes it practical to share a failing query with a teammate as a reproducible link rather than a Slack conversation about “what happens if the payload looks like this.”
The workflow is: paste the real payload, write the query, verify the output, then copy the query into your codebase. Faster debugging, fewer production extraction bugs, and easier team collaboration.
Payloads and queries are processed locally in your browser. jq runs via WebAssembly (jq-web), JSONPath via jsonpath-plus, and XPath via the browser's native DOM APIs. Nothing is uploaded to CodeAva servers and nothing is stored between sessions. Shareable permalinks encode state in the URL itself — the payload is compressed client-side with LZ-string, not sent to a server. Large payloads may affect browser memory and performance.
Why a jq, JSONPath, and XPath workbench?
Data extraction is still trial-and-error in most engineering workflows. A developer writing a jq filter for a CI pipeline pastes the payload into a terminal, tweaks the filter, re-runs, reads a cryptic error, adjusts, and iterates. A QA engineer testing a JSONPath assertion copies the response body, opens a browser tab, pastes it, tries the expression, and manually checks the output. An integration engineer debugging an XPath against an XML feed switches between documentation, a local XML file, and an online evaluator.
jq, JSONPath, and XPath solve related but different problems. jq is a full transformation language for JSON. JSONPath is a selection language for JSON. XPath is a navigation language for XML and HTML DOM structures. All three are useful. None of them have a great debugging experience out of the box.
This workbench puts all three engines in one interface with live evaluation, readable error explanations, payload-aware path hints, and multiple output views. It runs locally in the browser — no server round-trips, no data uploads — and supports shareable permalinks so you can send a colleague the exact payload, query, and result state instead of describing it in a message.
What this tool helps with
When to use it
- Extracting fields from API responsespaste a real JSON response and write the jq or JSONPath query to select the fields you need.
- Filtering nested JSON arraysuse jq select() or JSONPath filter expressions to narrow arrays by field values, conditions, or types.
- Testing jq transforms before CI/scriptsverify that your jq filter produces the expected output before embedding it in a pipeline or deployment script.
- Writing JSONPath for test automationbuild and verify JSONPath assertions against real API payloads before adding them to REST Assured, Postman, or Karate test suites.
- Evaluating XPath against XML feedstest XPath queries against RSS feeds, SOAP responses, or XML configuration files with namespace awareness.
- XPath on HTML for scraping or testingparse HTML documents and evaluate XPath queries using the browser's native DOM parser — useful for Selenium, Playwright, and scraping workflows.
- Debugging failed queries with clearer errorsthe error decoder translates cryptic jq, JSONPath, and XPath errors into plain-English explanations with suggested fixes.
When it's not enough
- Full jq pipeline orchestrationthis tool evaluates single jq expressions. For multi-file or multi-step jq pipelines, use the jq CLI or a dedicated orchestration tool.
- Large-scale XML transformationfor XSLT or complex XPath 2.0+ / XQuery workflows, a dedicated XML IDE is more appropriate. This tool supports XPath 1.0 via browser APIs.
- Production query executionthis is a testing and debugging workbench, not a production runtime. Use it to write and verify queries, then embed them in your codebase.
- Sensitive secrets in payloadswhile processing is local, follow your organization's policy on pasting secrets into browser tools. Shareable permalinks encode the payload in the URL.
How to use the workbench
- 1
Paste a payload or load a sample
Paste your JSON, XML, or HTML into the left editor pane. Or use the 'Load sample' dropdown to start with a pre-built example: API response, GitHub webhook, e-commerce order, XML catalog, RSS feed, or HTML page.
- 2
Choose jq, JSONPath, or XPath mode
Click the mode selector. jq and JSONPath require JSON input. XPath requires XML or HTML. The tool warns you clearly if the mode and format are incompatible.
- 3
Write or refine your query
Type your query in the top-right pane. Use the lightbulb button for payload-aware path suggestions, or open the cheat sheet for syntax examples. Results update live as you type with sensible debouncing.
- 4
Inspect the live output
Switch between Pretty, Raw, Tree, Table, and Values views in the result inspector. The summary card describes the result shape (e.g., 'Your jq filter returns 12 objects').
- 5
Use the error decoder if something fails
When a query or payload produces an error, the decoder shows the raw error, a plain-English explanation, and actionable fix suggestions — including jq null-iteration errors, XPath namespace issues, and JSONPath syntax problems.
- 6
Copy the result or share a permalink
Copy the query output for scripts, tests, or docs. Use the Share button to create a compressed permalink that preserves mode, payload, query, and format — shareable via Slack, email, or issue trackers.
Common issues and fixes
jq: cannot iterate over null
The field you are iterating (.[] or similar) is null or missing. Check the field path, or use select(. != null) or the alternative operator (.field // empty) to handle missing data.
Invalid JSON input
The payload is not valid JSON. Check for trailing commas (not allowed in JSON), single quotes (must be double), unquoted keys, or mismatched brackets. Use the Pretty button to auto-format if the JSON is valid but hard to read.
XML parse error
The XML payload has well-formedness issues. Check for unclosed tags, unescaped < or & characters, or a missing XML declaration. Every opening tag must have a matching closing tag.
XPath namespace mismatch
Your XPath references elements in a namespace but does not use namespace prefixes. If the XML uses xmlns="...", unprefixed XPath won't match. Use local-name() to match elements regardless of namespace, or add explicit prefix mappings.
JSONPath syntax error
The JSONPath expression is malformed. Ensure it starts with $, uses dot or bracket notation correctly, and that filter expressions use the ?(@.field == value) syntax.
Mode/format mismatch
The selected query mode is not compatible with the current payload format. jq and JSONPath require JSON. XPath requires XML or HTML. Switch the mode or the format to match.
XPath returns no nodes
The expression is syntactically valid but matched nothing. Check element names (they are case-sensitive), verify the document structure, and look for namespace issues if the XML uses xmlns attributes.