XPath 3.1 reference that's complete & succinct

Question

I've been reading through the W3 spec for XPath 3.1, and it's way too long for most to read (they'll just quit). Is there an abbreviated specification anywhere?

Our audience is users of our system that need to write an XPath statement to pull back the data they need. They are not programmers, they are business users. And they want to find a solution to their specific need as quickly as possible when they get stuck.

Update: First off, I totally agree with @kjhughes comment below "intrinsic tension". And I think Michael brings up a good point that the quick guide should be the main use - remove the edge cases. And reduce notes to a minimum (again no edge cases), but yes to examples.

What we have used for years is this tutorial, it tends to have a good balance between simplicity and teach all the basics. And this one is not bad.

But neither discusses either XPath 3.1 or crafting XPath for a JSON file. Is there anything equivalent out there.

As an example, here's three basic items I'm still struggling with:

1. What's the syntax for a basic query. Using Southwind.json is it "/Employees/Employee" to get a list of all the employee nodes (I can't successfully load a JSON file in my code yet so I can't test this)?
2. Are maps ever returned from an XPath query/evaluate? From reading this it looks like you can create and use them, but you don't ever get them as a returned item for a query.
3. Are arrays only returned on queries of JSON? From reading this, I think that is the case. And this just maps to a JSON array - correct?

Answer 1

There's an intrinsic tension between complete & succinct.

For complete, there's no substitute for the official specification: XML Path Language (XPath) 3.1. If it seems too extensive for your needs, you're simply not the intended audience. We want language implementers to have a complete, precise standard specification against which to build libraries and tools. It's the whole point of having a specification.

For succinct, you'll necessarily sacrifice completeness, but here are some resources that might fit the bill as overviews or introductions:

• The general Wikipedia entry for XPath covers concepts common across versions as well as what's new from 1.0 to 2.0 to 3.0 and on to 3.1

• Saxonica has good, generic descriptions as part of their product documentation. Start with New features in XPath 3.1 and branch out to links from there per your interests/needs.

• Related Stack Overflow Q/A: What are the differences between versions of XPath (1.0, 2.0, 3.1)

---

Update per question update:

Our audience is users of our system that need to write an XPath statement to pull back the data they need. They are not programmers, they are business users. And they want to find a solution to their specific need as quickly as possible when they get stuck.

Business users ought to have a proper, application-specific GUI, not be expected to write raw XPaths or regex or SQL.

If you insist that your business users write XPaths, and if they're at least technically sophisticated, then your best bet would be to write casebook containing commonly used idioms and examples from which they can try to learn. Supplement with a presentation on XPath fundamentals.

Answer 2

The basic trouble is that XPath has become quite a big language, and the more concise the reference you construct, the less likely it is to contain the answer to every question you want to ask. For your specific questions:

What's the syntax for a basic query. Using Southwind.json is it "/Employees/Employee"

I'm not familiar with the dataset.

Are maps ever returned from an XPath query/evaluate?

Of course. The simplest query that returns a map is map{}.

Are arrays only returned on queries of JSON?

No. For example the query [1, 2, 3] returns an array, and there's no JSON involved.