XPath Property

Selects a specific element in the loaded XML/JSON content.

Syntax

public String getXPath();
public void setXPath(String XPath);

Remarks

XPath is used to navigate the XML or JSON content loaded by Parse by and selecting a specific element in the XML or JSON document. The value set to XPath will be a path to a specific element within the document, either using traditional XPath syntax (both XML and JSON) or JSONPath syntax (JSON only); notes on both are given below.

Note that there are a couple of things to keep in mind when using traditional XPath notation with JSON documents:

Since JSON arrays contains only values and not names, an empty name is used to reach these values. So, when navigating a JSON document, if you wish to reach the third element in an array, the XPath-style accessors to use would be [3].
Since JSON does not have to be contained in a root-level object, the bean automatically adds a root element to all JSON documents called "json". So when using an absolute XPath, be sure to prefix it with the /json accessor.

After setting XPath with a valid XPath or JSONPath, the following properties are populated:

XPath Syntax

XPath syntax is available for both XML and JSON documents. An XPath is a series of one or more element accessors separated by the / character, for example: /A/B/C/D. An XPath can be absolute (i.e., it starts with /), or it can be relative to the current XPath location.

The following are possible values for an element accessor, which operates relative to the current location specified by the XPath accessors which proceed it in the overall XPath string:


Accessor	Description
`name`	The first element with a particular name. Can be `*`.
`[i]`	The i-th element.
`name[i]`	The i-th element with a particular name.
`[last()]`	The last element.
`[last()-i]`	The element i before the last element.
`name[@attrname="attrvalue"]`	The first element with a particular name that contains the specified attribute-value pair. >Supports single and double quotes. (XML Only)
`.`	The current element.
`..`	The parent element.

Note: XPath indices are 1-based.

XPath Examples

Assume you have the following XML document loaded into the bean:

<firstlevel>
  <one>value</one>
  <two>
    <item>first</item>
    <item>second</item>
  </two>
  <three>value three</three>
</firstlevel>

Or, alternatively, the following JSON document:

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}

Here are some examples of valid XPaths:


Description	XML XPath	JSON XPath
Document root	`/`	`/json`
Specific element	`/firstlevel/one`	`/json/firstlevel/one`
i-th child	`/firstlevel/two/item[2]`	`/json/firstlevel/two/[2]`

This is not an exhaustive list by any means, but should provide a general idea of the possibilities.

JSONPath Syntax

JSONPath syntax is available only for JSON documents. JSONPath also uses accessors, but you string them together differently. You may either separate them with . characters (dot notation), or just surround each one with square brackets [] and single-quote the name (bracket notation). For example, the following JSONPaths are the same, and would select the same element in the JSON snippet as the last XPath in the XPath examples table (both of which are shown above):

$.firstlevel.two[1]
$['firstlevel']['two'][1]

However, in either case, a JSONPath must begin with a $ (which should not be enclosed in square brackets if using that syntax type). The $ character represents the JSON document's "root".

The following accessors are supported (shown in both dot and square bracket syntaxes):


`.` Accessor	`[]` Accessor	Description
`name`	`['name']`	The first element with a particular name. Can be `*`.
`name[i]`	`['name'][i]`	The i-th subelement in a particularly-named array or object element.
`name[last()]`	`['name'][last()]`	The last subelement in a particularly-named array or object element.
`name[last()-i]`	`['name'][last()-i]`	The subelement i before the last one in a particularly-named array or object element.
`@`	`['@']`	The current element.

Notes:

JSONPath indices are 0-based.
In any accessor that contains name or ['name'], you can use $ instead. For example, $[1].
When using dot notation, you can place a . between names and element indices. E.g., name[i] and name.[i] are the same.

JSONPath Examples

Using the same JSON snippet as shown in the XPath Examples section, the following table shows a non-exhaustive list of valid JSONPaths (which are equivalent to the same rows in the XPath table):


Description	Dot Notation	Bracket Notation
Document root	`$`	`$`
Specific element	`$.firstlevel.one`	`$['firstlevel']['one']`
i-th child	`$.firstlevel.two[1]`	`$['firstlevel']['two'][1]`

This property is not available at design time.