Several of FairCom's JSON API properties, including "propertyPath" and "recordPath", use JSONPath to specify the location of properties in a JSON document.
FairCom's implementation of JSONPath
- It uses the period "." character to define the nesting of properties in objects, such as "personNames.givenName".
- It uses straight brackets to define the position of a value in an array, such as "favoriteFoods[0]".
- The first item in an array is always 0.
- It supports the last keyword to refer to the last item in the array, such as "favoriteFoods[last]".
- It also supports referencing elements before the last item in the array, such as "favoriteFoods[last-1]" and "favoriteFoods[last-2]".
- FairCom's JSONPath does not use "$." to refer to the root object.
- If you use an online JSONPath evaluator to create JSONPath expressions, such as jsonpath.com, you may need to add "$." to the JSONPath to make it work, such as $.personNames.legalName[1].
- When you want to use a JSONPath that you created in an online JSONPath evaluator, you need to remove the "$." from you JSONPath expressions.
Example JSON document with property paths
The "jsonPaths" property contains a JSONPath for each property in the document.
{
"id": 1,
"type": "person",
"birthdate": "2000-01-01",
"favoriteFoods": [ "pizza", "ice cream", "steak" ],
"personNames": {
"givenName": "Michael",
"surname": "Bowers",
"nickname": "Mike",
"legalName": [ "Michael", "Bowers" ]
},
"emailList": [
{
"emailPurpose": "home",
"emailAddress": "myhome@gmail.com"
},
{
"emailPurpose": "work",
"emailAddress": "mywork@gmail.com"
}
]
}
Examples using JSONPath property to read and write JSON values
JSONPath can refer to any value in the previous JSON document.
JSONPath examples
| JSONPath | Value |
|---|---|
| "id" | 1 |
| "type" | "person" |
| "birthdate" | "2000-01-01" |
| "favoriteFoods" | [ "pizza", "ice cream", "steak" ] |
| "favoriteFoods[0]" | "pizza" |
| "favoriteFoods[1]" | "ice cream" |
| "favoriteFoods[2]" | "steak" |
| "favoriteFoods[last]" | "steak" |
| "favoriteFoods[last-1]" | "ice cream" |
| "favoriteFoods[last-2]" | "pizza" |
| "personNames" | {
"givenName": "Michael",
"surname": "Bowers",
"nickname": "Mike",
"legalName": [ "Michael", "Bowers" ]
} |
| "personNames.givenName" | "Michael" |
| "personNames.surname" | "Bowers" |
| "personNames.nickname" | "Mike" |
| "personNames.legalName" | [ "Michael", "Bowers" ] |
| "personNames.legalName[0]" | "Michael" |
| "personNames.legalName[1]" | "Bowers" |
| "emailList" | "emailList":
[
{
"emailPurpose": "home",
"emailAddress": "myhome@gmail.com"
},
{
"emailPurpose": "work",
"emailAddress": "mywork@gmail.com"
}
]
|
| "emailList[0]" | {
"emailPurpose": "home",
"emailAddress": "myhome@gmail.com"
}
|
| "emailList[0].emailPurpose" | "home" |
| "emailList[0].emailAddress" | "myhome@gmail.com" |
| "emailList[1]" | {
"emailPurpose": "work",
"emailAddress": "mywork@gmail.com"
}
|
| "emailList[1].emailPurpose" | "work" |
| "emailList[1].emailAddress" | "mywork@gmail.com" |
FairCom JSONPath features
FairCom supports the following JSONPath features to read or write one JSON value:
- The property selector . identifies a JSON property, such as .humidity.
- You can nest property selectors, such as .humidity.temperature.
- The array element selector [n] uses a zero-based number to specify one array element, such as .temperatures[0].
- You can also use .temperatures[last] to retrieve the last element.
- You can also use .temperatures[last-1] to retrieve the element before the last element.
- You can mix property and array element selectors, such as .humidity.temperatures[2].celsius.
FairCom JSONPath limitations
FairCom's JSONPath feature supports reading and writing one JSON value. Thus, it does not support JSONPath features that return multiple values:
- The recursive descent .. wildcard returns all values associated with the specified property name, such as ..name.
- The wildcard expression * selects all child items, such as all the array items in names[*] or all the child properties in address.*.
- Array range expressions select more than one value, such as [index1, index2, ...], [start:end], [start:], [:n], [-n:], [?(expression)], and [(expression)].
- @ to represent the current node in expressions.
- The root expression $ typically occurs at the beginning of the JSONPath statement. FairCom assumes JSONPath starts with the root node; thus, you must omit $.
- FairCom also does not support embedded expressions.