DEV Community: Souvik Pramanik

JSONPath Cheat Sheet: Syntax, Examples & Common Mistakes

Souvik Pramanik — Tue, 01 Sep 2026 23:42:14 +0000

JSONPath looks simple until you actually need a filter, a slice, or a recursive match - then the handful of symbols that looked obvious start behaving unpredictably. This is a complete reference: every operator with a working example, a real query built step by step, the mistakes that most often cause a silent empty result, and how JSONPath stacks up against JMESPath and XPath.

Full syntax reference

Syntax	Meaning	Example
`$`	Root of the document - every expression starts here	`$`
`.prop` / `['prop']`	Child property, by dot or bracket notation	`$.user.name`
`[*]`	Wildcard - all items in an array, or all properties of an object	`$.items[*]`
`..`	Recursive descent - matches a property at any depth	`$..price`
`[0]`, `[-1]`	Index into an array (some libraries support negative indices)	`$.items[0]`
`[0,2,5]`	Union - multiple indices or property names at once	`$.items[0,2,5]`
`[start:end:step]`	Array slice, end-exclusive, step optional	`$.items[1:5:2]`
`[?(<expr>)]`	Filter - keep only elements where `<expr>` is true	`$.items[?(@.price < 10)]`
`@`	The current element being tested, used inside a filter	`@.inStock === true`
`=~ /regex/i`	Regex match inside a filter (library extension, not core spec)	`@.name =~ /^a/i`
`&&` / `\	\	`

Worked example: querying a real API-shaped response

Say an API returns this order history payload:

{
  "customer": "Alex",
  "orders": [
    { "id": 101, "status": "shipped", "total": 42.50, "items": [{ "sku": "A1", "qty": 2 }] },
    { "id": 102, "status": "pending", "total": 15.00, "items": [{ "sku": "B4", "qty": 1 }] },
    { "id": 103, "status": "shipped", "total": 8.25,  "items": [{ "sku": "A1", "qty": 1 }] }
  ]
}

Build the query one requirement at a time:

"Give me every order total." Walk from the root into the array and grab the field: $.orders[*].total → [42.50, 15.00, 8.25]
"Only shipped orders." Add a filter before drilling into the field: $.orders[?(@.status === 'shipped')] → the two matching order objects
"Only shipped orders over $10." Combine two conditions with &&: $.orders[?(@.status === 'shipped' && @.total > 10)] → just order 101
"Just the SKUs from those orders, wherever they appear." Recursive descent skips having to know the exact nesting depth: $.orders[?(@.status === 'shipped')]..sku → ["A1", "A1"]

That's the general pattern for any JSONPath query: start at $, narrow with a filter as early as possible (it's cheaper to filter the array once than to grab everything and post-process), then drill into the exact field you need.

Mistakes that cause a silent empty result

Forgetting the leading $. Every valid expression starts at the root - orders[*].total without the $ is not a valid path in most libraries.
Comparing a number to a quoted string in a filter. @.id == "101" when id is a number will not match - drop the quotes: @.id == 101.
Assuming $..price and $.price are the same. The single-dot version only matches price directly under the root; if it's nested, you need the recursive .. form.
Using a property with a dot or space without bracket notation. $.display name breaks - use $['display name'] instead.
Not confirming the array vs. object level first. If a path returns nothing, back it off one segment at a time ($.orders, then $.orders[*], then add the filter) to see exactly where it stops matching.

JSONPath vs. JMESPath vs. XPath

All three are query languages for structured data, but they're not interchangeable syntax for the same thing:

JSONPath - the most common choice for querying JSON in JavaScript/Node tooling and API testing tools; uses $, [?()], ...
JMESPath - used heavily in AWS CLI/SDK output filtering (--query); has its own pipe-based syntax (|) and built-in functions (sort_by(), contains()) that JSONPath doesn't have.
XPath - the original of the three, built for XML, with axis-based navigation (//, parent::) that predates JSON entirely.

If you already know one, the other two feel roughly similar in spirit - "select nodes matching a pattern" - but none of the operators are directly transferable; check the target tool's docs rather than assuming JSONPath syntax works in a JMESPath-based tool like the AWS CLI.

Try it

Paste your own JSON into the JSONPath Evaluator and test any expression from this cheat sheet directly against it - entirely in your browser, nothing uploaded.

FAQ

Is JSONPath an official standard?
There's an RFC (RFC 9535) that standardizes a core JSONPath syntax, but many libraries - including most JavaScript ones - predate it and add their own extensions (like =~ regex filters). Stick to what your specific library documents if you hit inconsistent behavior between implementations.

Why does my filter expression return nothing?
The single most common cause is an operator or type mismatch inside [?()] - for example comparing a number field to a quoted string, or forgetting that @ refers to the current item being tested, not the root. Isolate the problem by first running the path without the filter to confirm you're even at the right array.

What's the difference between $.a.b and $..b?
$.a.b is an exact path - it only matches b directly under a. $..b is recursive descent - it matches a property named b anywhere in the document, at any depth. The second is more powerful but slower and easier to get unexpected matches from on a large document.

Can JSONPath modify or delete data, not just read it?
The JSONPath language itself is read-only - it selects and returns matching values. Some libraries add write/delete helpers on top, but that's a library-specific extension, not part of JSONPath itself.

Validating OpenAI & Anthropic Tool-Calling Schemas

Souvik Pramanik — Mon, 24 Aug 2026 19:23:25 +0000

Tool/function calling only works as well as the schema behind it. A structurally valid schema can still make an agent call your tool wrong — and a subtly broken one can fail silently. This post covers what actually goes wrong, how to catch it before it reaches a live model, and a worked example.

The two formats, side by side

OpenAI and Anthropic both wrap a standard JSON Schema in a tool/function definition — they just nest it under a different field name.

OpenAI (function calling):

{
  "name": "get_weather",
  "description": "Get the current weather for a given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City and state, e.g. San Francisco, CA" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"],
    "additionalProperties": false
  }
}

Anthropic (tool use): identical shape, just input_schema instead of parameters.

{
  "name": "get_weather",
  "description": "Get the current weather for a given location.",
  "input_schema": {
    "type": "object",
    "properties": { "location": { "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } },
    "required": ["location"],
    "additionalProperties": false
  }
}

Five things that go wrong — and are easy to miss

Root type isn't "object". Both providers expect tool arguments to arrive as a JSON object. A schema whose root type is anything else gets rejected or behaves unpredictably — a one-line fix, but the single most common structural mistake.
Missing or vague description fields. Not a JSON Schema violation — description isn't required by the spec — but it's what the model actually reads to decide when and how to call the tool, and what to put in each argument. A schema that's technically valid but under-described leads to wrong calls, not errors.
No additionalProperties: false. Without it, a model that hallucinates an extra argument still passes validation. Setting it to false catches the hallucination immediately instead of letting it reach your function's implementation.
Overly nested or ambiguous schemas. Deep nesting, ambiguous oneOf branches, or a huge flat list of optional fields all increase the model's chance of guessing wrong. Flatter, more explicit schemas produce more reliable calls.
Enum values that don't match what you actually accept. An enum that's stale relative to your function's real implementation is a silent mismatch — the schema will validate, but the call can still fail downstream.

A pre-deploy checklist

Is the whole tool definition valid JSON?
Are name and description both present and specific?
Is the parameter schema's root type set to "object"?
Is additionalProperties: false set, unless you have a specific reason not to?
Does the parameter schema actually compile as valid JSON Schema (no typos in keywords, correct nesting)?
Does a realistic sample arguments payload — the kind of JSON the model would actually send — satisfy the schema?

All six of these are checkable offline, without a live model call. I built a free tool that runs exactly this checklist: AI Tool / Function Calling Schema Validator — paste a tool definition, pick OpenAI or Anthropic, and it validates structure, compiles the schema, and checks sample arguments against it, entirely in your browser, no API calls.

Worked example: fixing a broken schema

Before — technically parseable, but has three of the problems above:

{
  "name": "search",
  "parameters": {
    "properties": {
      "q": { "type": "string" },
      "limit": {}
    }
  }
}

No description (the model has almost nothing to go on), no root type: "object", no required, and limit has no type at all.

After:

{
  "name": "search",
  "description": "Search the product catalog by keyword and return matching items.",
  "parameters": {
    "type": "object",
    "properties": {
      "q": { "type": "string", "description": "Search keywords" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Max results to return" }
    },
    "required": ["q"],
    "additionalProperties": false
  }
}

Try it

Paste your own tool definition into the AI Tool Schema Validator and run through this exact checklist automatically, including testing sample arguments against the compiled schema. Nothing is sent to OpenAI, Anthropic, or any server — it's a structural, offline check only.