About this article
This article was created using an automated generation workflow powered by generative AI. We review the Microsoft Learn ConvertTo-Json specifications and compare Depth settings when converting deep objects to JSON using safe dummy data. No PowerShell execution was performed during the creation of this article.Verification Status: 📘 Official Specification Verified – PowerShell Execution Unverified
Information verification date: October 2, 2026.
When JSON for APIs does not form the expected hierarchy, check the Depth parameter of ConvertTo-Json.
Creating a nested structure
$data = [pscustomobject]@{
Name = 'demo'
Settings = [pscustomobject]@{
Network = [pscustomobject]@{
Proxy = [pscustomobject]@{ Enabled = $false; Port = 8080 }
}
}
}
$data | ConvertTo-Json -Depth 2
$data | ConvertTo-Json -Depth 5
According to Microsoft Learn, the default value for Depth is 2. Warnings may be issued for inputs that exceed the specified Depth.
Reloading to verify
$json = $data | ConvertTo-Json -Depth 5 $check = $json | ConvertFrom-Json $check.Settings.Network.Proxy.Port
Check whether port 8080 is reachable.
Changing a single location
Change Depth to 3 and compare the output and warnings.
flowchart TD
A["Object"] --> B["ConvertTo-Json"]
B --> C{"Depth十分?"}
C -->|Yes| D["必要階層"]
C -->|No| E["警告/表現を確認"]
For enterprise usage
Avoid setting Depth to the maximum value arbitrarily; instead, understand the structure required by the API and specify a sufficient value.
Why Depth issues can lead to API failures
Even if an object in PowerShell appears correct, it is serialized into a different representation called JSON immediately before being passed to the API. If the required hierarchy cannot be expressed at this stage, it leads to hard-to-diagnose issues where values exist in PowerShell but settings are missing at the destination.
Therefore, rather than simply viewing the JSON string prior to transmission, convert it back using ConvertFrom-Json and verify whether the required properties can be traversed. Increasing Depth is not always the correct answer;the key point is to understand the depth required by the API contract and confirm that the structure is preserved.This concludes the overview.
