PsJsonQuery

PsJsonQuery is a PowerShell native JSON query class that can be used to simplify working with JSON in PowerShell. The ConvertFrom-Json cmdlet makes some operations difficult by returning JSON as an object type. As a result, PsJsonQuery was created to help in situations where simply using the JSON object returned by ConvertFrom-Json can be difficult. Additionally, this class is especially useful when working in an environment where jq is inaccessible, but PowerShell is not. PsJsonQuery functions similarly to jq, but with a few differences:

• Queries follow the same basic format as jq filters.
• PsJsonQuery typically has 2 space tabs instead of 4. This is why output is usually saved in a different file from the input file.
• Any changes made using PsJsonQuery can be seen immediately if calling a PsJsonQuery method, but will not be outputted to a file until a Save() call is completed.
• Square brackets "[]" are optional in a query returning an array (i.e. .json.query.array[].property can also be .json.query.array.property).
• Queries output in JSON format, so ConvertFrom-Json should be used before doing any object manipulation after a query.

Setup

Install-Module PsJsonQuery
Import-Module PsJsonQuery
$Pq=New-PsJsonQuery-JsonFilePath "example.json"

Run Tests with Pester

To test with Pester, from the repository root run:

Invoke-Pester

Example Usage Cases

Using sample JSON for example.json:

{
"root": {
"leaf": "leafValue",
"array": [
{
"arrayLeaf": "arrayLeafValue",
"property": "value"
},
{
"arrayInt": 100,
"property": "anotherValue"
}
]
}
}

Instantiate PsJsonQuery object:

$Pq= [PsJsonQuery]::new("example.json")
# or$Object=Get-Content"example.json"|ConvertFrom-Json$Pq= [PsJsonQuery]::new($Object)

Instantiate PsJsonQuery object with New-PsJsonQuery:

$Pq=New-PsJsonQuery-JsonFilePath "example.json"# or$Object=Get-Content"example.json"|ConvertFrom-Json$Pq=New-PsJsonQuery-JsonFileObject $Object

Obtain a specific setting:

$Pq.Query(".root.leaf")

Returns:

"leafValue"

Obtain a JSON object:

$Query=".root.array"# or$Query=".root.array[]"$Pq.Query($Query)

Returns:

{
[
{
"arrayLeaf": "arrayLeafValue",
"property": "value"
},
{
"arrayInt": 100
}
]
}

Obtain an array element:

$Pq.Query(".root.array[0]")

Returns:

{
"arrayLeaf": "arrayLeafValue",
"property": "value"
}

Obtain an array element by property value (as an object):

$Query=".root.array"# or$Query=".root.array[]"$Element=$Pq.Query($Query) |ConvertFrom-Json|Where-Object-Property property -EQ"value"

Returns:

$ArrayLeaf=$Element.arrayLeaf$Property=$Element.property

Obtain an array element by property value (as JSON):

$Query=".root.array"# or$Query=".root.array[]"$property=$Pq.Query($Query) |ConvertFrom-Json|Where-Object-Property property -EQ"value"|ConvertTo-Json-Depth 99

Returns:

{
"arrayLeaf": "arrayLeafValue",
"property": "value"
}

Filter array elements by property:

$Query=".root.array.property"# or$Query=".root.array[].property"$Property=$Pq.Query($Query)

Returns:

[
"value",
"anotherValue"
]

Obtain paths to all leaf nodes, value of each leaf node in a hashtable:

$PathsHashtable=$Pq.Paths()

Returns hashtable in the following key, value format:

$PathsHashtable[".root.leaf"] ="leafValue"$PathsHashtable[".root.array[0].arrayLeaf"] ="arrayLeafValue"$PathsHashtable[".root.array[0].property"] ="value"$PathsHashtable[".root.array[1].arrayInt"] =100$PathsHashtable[".root.array[1].property"] ="anotherValue"

Change the value of a path, then get updated JSON:

$Pq.SetPath(".root.leaf",999)
$Pq.Save("file.modified.json")

Returns:

{
"root": {
"leaf": 999,
"array": [
{
"arrayLeaf": "arrayLeafValue",
"property": "value"
},
{
"arrayInt": 100,
"property": "anotherValue"
}
]
}
}

Obtain all paths to a value:

$Paths=$Pq.GetPathsToValue("arrayLeafValue")

Returns:

$Paths[0] =".root.array[0].arrayLeaf"