Document the full Data Navigator path syntax

[lmajano]

Description

Follow-up to #56. The Data Navigator page summarised the supported path expressions in one sentence:

Paths support dot-notation, array indexes, wildcards, filters, recursive descent and the rest of the JSONPath-style expression set.

That both undersold the syntax and omitted slices entirely. Anyone wanting the actual grammar had to leave the TestBox book and go read the BoxLang docs.

This replaces that sentence with a proper Path Syntax reference table covering every form dataNavigate() accepts.

Syntax	Example	Matches
Dot notation	app.settings.port	The value at that key path
Array index	users[1]	The first user — indexing is 1-based
Recursive descent	..name	Every name key at any depth
Wildcard, keys	app.settings.*	Every value under settings
Wildcard, array	users[*].name	The name of every user
Slice	primes[1:3]	Elements 1 through 3, inclusive
Open-ended slice	primes[2:]	Element 2 through the end
Filter	users[?(@.age > 18)].name	The name of every user over 18

Also added

• A callout that array indexing is 1-based. It follows the language convention rather than JSONPath's usual 0-based indexing, so users[1] is the first element. This is the detail most likely to bite someone arriving from JSONPath elsewhere.
• The filter operator set (==, !=, >, <, >=, <=), that @ refers to the current element, and that whitespace inside a filter is tolerated.
• Guidance on which retrieval method to reach for: a path that resolves to many values — wildcard, slice, recursive descent or filter — belongs with queryPath(), while path() and the toHavePath*() matchers resolve to the first match. That mirrors get() vs query() on the underlying navigator.
• Worked filter, recursive-descent and slice examples under queryPath(), which previously only demonstrated wildcards.

A note on the slice example

Slices get their own small example array:

var primes = { "values" : [ 2, 3, 5, 7, 11 ] }

expect( primes ).queryPath( "values[1:3]" ).toHaveLength( 3 )   // 2, 3, 5
expect( primes ).queryPath( "values[4:]" ).toHaveLength( 2 )    // 7, 11

The page's shared data fixture has a single-element users array, so demonstrating a slice against it would have meant asserting how an out-of-range slice behaves — clamped or not — which I did not want to state without confirming. A five-element array makes the inclusive 1-based window self-evident instead.

Verification

Path syntax was confirmed against the BoxLang documentation (Data Navigators, DataNavigate BIF) rather than inferred from the TestBox side. JSONPath-style string expressions are available as of BoxLang 1.14.0.

Page checks: code fences balanced, all three {% hint %} blocks balanced, no tabs (BoxLang-only page, per CLAUDE.md), all fences ```java, and the #path-syntax anchor resolves to a real heading.

🤖 Generated with Claude Code

https://claude.ai/code/session_0126haQX77C4MLiK3fxwQ59A

---

Generated by Claude Code