|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > PSJ. - JSON Operations |
Understanding JSON Paths in PSJ. |
Top |
SPR Script Language
Understanding JSON Paths in PSJ.
A guide to using Universal Path Syntax (JSON Pointer and Dot-Notation) to target elements with the PSJ. library.
Intention
In the PSJ. library, JSON paths are crucial for locating specific elements within a JSON document (identified by a document handle like $$DOC). These paths guide commands like PSJ.GetStr or PSJ.SetStr to the exact object key or array index you want to interact with. The PSJ. library supports a flexible "Universal Path Syntax" that accepts both the standard JSON Pointer (RFC 6901) format and the commonly used Dot-Notation.
Supported Path Syntaxes
1. JSON Pointer (RFC 6901)
• Separator: Uses a forward slash (/) to separate keys and array indices.
• Root: A single forward slash (/) represents the root of the document.
• Object Keys: Specified directly after the slash (e.g., /person/name).
• Array Indices: Specified as numbers (0-based) after the slash (e.g., /items/0).
• Escaping: Keys containing `/` or `~` must be escaped as `~1` and `~0` respectively (e.g., /a~1b/c~0d refers to key `c~d` within object `a/b`). The library handles this decoding automatically.
2. Dot-Notation
• Object Keys Separator: Uses a dot (.) to separate keys (e.g., person.name).
• Array Indices: Uses square brackets ([]) enclosing the 0-based index (e.g., items[0]).
• Nesting: Combine dots and brackets (e.g., person.hobbies[1], data[0].results).
• Root: Assumed to start from the root node of the document handle provided. An empty path (`""`) may target the root node itself if it's a primitive type (less common).
Illustration
Let’s use a sample JSON document to illustrate both path syntaxes.
📝 Sample JSON Document:
{"person": {"name": "Alice","age": 25,"isStudent": false,"hobbies": ["reading", "gaming", "hiking"],"address": {"city": "New York","zip": 10001}}, "items": null}
Assume the above JSON is parsed into document handle $$DOC.
📝 Example 1: Get Name (String)
PSJ.GetStr|$$DOC|/person/name|$$NAME // JSON Pointer
PSJ.GetStr|$$DOC|person.name|$$NAME // Dot-Notation
Result: $$NAME = "Alice"
📝 Example 2: Get Second Hobby (Array Element)
PSJ.GetStr|$$DOC|/person/hobbies/1|$$HOBBY // JSON Pointer (Index 1)
PSJ.GetStr|$$DOC|person.hobbies[1]|$$HOBBY // Dot-Notation (Index 1)
Result: $$HOBBY = "gaming"
📝 Example 3: Get City (Nested Object)
PSJ.GetStr|$$DOC|/person/address/city|$$CITY // JSON Pointer
PSJ.GetStr|$$DOC|person.address.city|$$CITY // Dot-Notation
Result: $$CITY = "New York"
📝 Example 4: Set Age (Number)
PSJ.SetNum|$$DOC|/person/age|26 // JSON Pointer
PSJ.SetNum|$$DOC|person.age|26 // Dot-Notation
Result: The age value in the JSON document $$DOC is updated to 26.
📝 Example 5: Append to Array Using Path
PSJ.AppendStr|$$DOC|/person/hobbies|swimming // JSON Pointer
PSJ.AppendStr|$$DOC|person.hobbies|biking // Dot-Notation
Result: The strings "swimming" and "biking" are added to the end of the hobbies array.
📝 Example 6: Check a Null Value
PSJ.GetNull|$$DOC|/items|$$ISNULL // JSON Pointer
PSJ.GetNull|$$DOC|items|$$ISNULL // Dot-Notation
Result: $$ISNULL = 1 (True), because the "items" key has a null value.
Remarks
§ The PSJ library parses the path string internally and determines which syntax is being used.
§ Ensure your path string correctly matches the structure of your JSON document. Case sensitivity for keys matters (e.g., "person" is different from "Person").
§ Array indices are always 0-based (0 for the first element, 1 for the second, etc.) in both syntaxes when parsed internally, even if some commands might use 1-based indexing for their parameters (like PSJ.ChildAt).
§ Commands like PSJ.GetByPath (with the create flag set) or the PSJ.Set* commands will automatically create the necessary objects and arrays along the path if they don't exist.
§ If a path is invalid or doesn't lead to the expected type of element (e.g., using an object key on an array), the command will typically fail and set an error code. Use PSJ.ErrCode and PSJ.ErrMsg to check for errors.
See also:
• PSJ. - JSON Operations Overview (WsLnTre)
• Path Navigation & Querying Chapter