JSON operations (ConvertFrom-Json, ConvertTo-Json) in PowerShell - Deep Dive

Overview - JSON operations (ConvertFrom-Json, ConvertTo-Json)

What is it?

JSON operations in PowerShell involve converting data between JSON text and PowerShell objects. ConvertFrom-Json takes JSON text and turns it into objects you can work with in scripts. ConvertTo-Json does the opposite: it turns PowerShell objects into JSON text for sharing or saving. These commands make it easy to handle data in a common format used by many systems.

Why it matters

Without these commands, working with JSON data in PowerShell would be slow and error-prone. JSON is everywhere—APIs, config files, and data exchange. Being able to convert JSON to objects and back lets you automate tasks, integrate systems, and handle data smoothly. Without this, scripts would struggle to understand or produce JSON, limiting automation power.

Where it fits

Before learning JSON operations, you should understand basic PowerShell objects and strings. After mastering these commands, you can move on to working with APIs, REST calls, and advanced data manipulation in PowerShell scripts.

Mental Model

Core Idea

ConvertFrom-Json turns JSON text into PowerShell objects, and ConvertTo-Json turns PowerShell objects back into JSON text.

Think of it like...

It's like translating a letter written in a foreign language (JSON text) into your native language (PowerShell objects) so you can understand and work with it, then writing your reply back in that foreign language.

JSON Text (string)  ──ConvertFrom-Json──▶ PowerShell Object
PowerShell Object  ──ConvertTo-Json──▶ JSON Text (string)

Build-Up - 7 Steps

1

Foundation

Understanding JSON Text Format

Concept: Learn what JSON text looks like and why it is used.

JSON is a text format that stores data as key-value pairs and lists. It uses braces { } for objects and brackets [ ] for arrays. For example: {"name":"Alice","age":30} is JSON text representing a person.

Result

You can recognize JSON text and understand its structure as readable text.

Knowing JSON text format helps you see why conversion to objects is needed for easy data use.

2

Foundation

PowerShell Objects Basics

Concept: Understand what PowerShell objects are and how they store data.

PowerShell objects hold data with properties and methods. For example, a person object might have properties Name and Age. Objects let you access data easily like $person.Name or $person.Age.

Result

You can create and use simple PowerShell objects to hold data.

Understanding objects is key because ConvertFrom-Json creates these from JSON text.

3

Intermediate

Using ConvertFrom-Json to Parse JSON

🤔Before reading on: do you think ConvertFrom-Json returns text or objects? Commit to your answer.

Concept: Learn how ConvertFrom-Json turns JSON text into usable PowerShell objects.

Use ConvertFrom-Json with JSON text input to get objects. Example: $json = '{"name":"Bob","age":25}' $obj = $json | ConvertFrom-Json $obj.Name # Outputs 'Bob' $obj.Age # Outputs 25

Result

You get a PowerShell object with properties from the JSON text.

Understanding this conversion lets you work with JSON data naturally in scripts.

4

Intermediate

Using ConvertTo-Json to Create JSON Text

🤔Before reading on: do you think ConvertTo-Json changes objects or creates text? Commit to your answer.

Concept: Learn how ConvertTo-Json turns PowerShell objects into JSON text for sharing or saving.

Create an object and convert it to JSON text: $obj = [PSCustomObject]@{Name='Carol'; Age=28} $json = $obj | ConvertTo-Json $json # Outputs '{"Name":"Carol","Age":28}'

Result

You get JSON text representing the object data.

Knowing how to create JSON text lets you send data to APIs or save configs.

5

Intermediate

Handling Arrays and Nested Objects

🤔Before reading on: do you think ConvertFrom-Json can handle arrays and nested data? Commit to your answer.

Concept: Learn how JSON arrays and nested objects convert to PowerShell arrays and nested objects.

Example JSON with array and nested object: $json = '{"users":[{"name":"Dave","age":40},{"name":"Eve","age":35}]}' $obj = $json | ConvertFrom-Json $obj.users[0].name # Outputs 'Dave' $obj.users[1].age # Outputs 35

Result

You can access nested data and arrays as PowerShell objects and arrays.

Understanding nested structures is essential for real-world JSON data handling.

6

Advanced

Controlling JSON Output Formatting

🤔Before reading on: do you think ConvertTo-Json outputs all data by default or can you limit depth? Commit to your answer.

Concept: Learn how to control how deep ConvertTo-Json converts nested objects and how to format output.

ConvertTo-Json has a -Depth parameter to control nested levels: $obj = [PSCustomObject]@{Name='Frank'; Details = @{City='NY'; Zip=10001}} $json = $obj | ConvertTo-Json -Depth 2 $json # Includes nested Details object Without -Depth 2, nested objects may be truncated.

Result

You get full JSON text including nested objects when you set depth properly.

Knowing how to control depth prevents losing data in JSON output.

7

Expert

Performance and Limitations in Large JSON Handling

🤔Before reading on: do you think ConvertFrom-Json and ConvertTo-Json handle very large JSON efficiently? Commit to your answer.

Concept: Explore how these commands perform with large or complex JSON and their limitations.

ConvertFrom-Json and ConvertTo-Json are convenient but can be slow or memory-heavy with very large JSON files. They load entire data into memory. For huge JSON, consider streaming parsers or external tools. Also, some data types (like dates) may convert unexpectedly.

Result

You understand when to avoid these commands for performance reasons.

Knowing limits helps choose the right tool and avoid script slowdowns or crashes.

Under the Hood

ConvertFrom-Json parses JSON text by reading the string and building PowerShell objects in memory that mirror the JSON structure. It uses a JSON parser built into PowerShell that understands JSON syntax and converts it into PSCustomObjects and arrays. ConvertTo-Json serializes PowerShell objects by traversing their properties and converting them into JSON text, respecting the depth limit to avoid infinite recursion.

Why designed this way?

PowerShell was designed to work with objects, not just text. JSON is a popular data format, so these commands bridge text and objects seamlessly. The design favors ease of use and integration with PowerShell's pipeline. Alternatives like manual parsing would be complex and error-prone. The depth parameter balances completeness with performance and prevents infinite loops in nested objects.

JSON Text (string) ──▶ Parser ──▶ PowerShell Objects
PowerShell Objects ──▶ Serializer ──▶ JSON Text (string)

[ConvertFrom-Json]          [ConvertTo-Json]
       │                          ▲
       ▼                          │
  JSON Parser             Object Traversal
       │                          │
       ▼                          ▼
  PSCustomObjects           JSON Text Output

Myth Busters - 4 Common Misconceptions

Quick: Does ConvertFrom-Json return text or objects? Commit to your answer.

Common Belief: ConvertFrom-Json returns JSON text that you still need to parse.

Reality: ConvertFrom-Json returns PowerShell objects ready to use, not text.

Why it matters: Believing this leads to redundant parsing attempts and confusion in scripts.

Quick: Does ConvertTo-Json always output all nested data by default? Commit to your answer.

Common Belief: ConvertTo-Json outputs the entire object including all nested levels by default.

Reality: By default, ConvertTo-Json limits depth to 2, truncating deeper nested data unless you specify -Depth.

Why it matters: Missing nested data causes incomplete JSON output, breaking integrations or data exchange.

Quick: Can ConvertFrom-Json handle very large JSON files efficiently? Commit to your answer.

Common Belief: ConvertFrom-Json can handle any size JSON file efficiently without issues.

Reality: ConvertFrom-Json loads the entire JSON into memory, which can cause slowdowns or crashes with very large files.

Why it matters: Using it blindly on huge files can cause scripts to fail or consume excessive resources.

Quick: Does ConvertTo-Json preserve all PowerShell object types exactly? Commit to your answer.

Common Belief: ConvertTo-Json preserves all PowerShell object types exactly in JSON output.

Reality: ConvertTo-Json converts objects to JSON-compatible types, sometimes losing type details like dates or custom objects.

Why it matters: Assuming perfect preservation can cause data misinterpretation when JSON is read back.

Expert Zone

1

ConvertTo-Json's -Depth parameter defaults to 2, but complex objects often need higher depth to avoid data loss.

2

ConvertFrom-Json creates PSCustomObjects, which behave differently than some native PowerShell types, affecting property access and methods.

3

When multiple JSON objects are streamed (e.g., in a file), ConvertFrom-Json processes only one at a time, requiring special handling for arrays or streams.

When NOT to use

Avoid ConvertFrom-Json and ConvertTo-Json for extremely large JSON files or streaming data; instead, use specialized JSON streaming parsers or external tools like jq. Also, for binary or non-JSON formats, these commands are not suitable.

Production Patterns

In production, these commands are used to parse API responses, generate configuration files, and automate data exchange. Scripts often combine ConvertFrom-Json with Invoke-RestMethod for web APIs, and ConvertTo-Json to prepare payloads. Handling nested data carefully with -Depth and validating JSON structure before processing are common best practices.

Connections

REST APIs

Builds-on

Understanding JSON operations is essential for interacting with REST APIs, which commonly use JSON for requests and responses.

Data Serialization

Same pattern

JSON operations in PowerShell are a form of data serialization and deserialization, a concept used across programming to convert data structures to text and back.

Language Translation

Analogy

Just like translating languages enables communication between people, converting JSON to objects and back enables communication between systems and scripts.

Common Pitfalls

#1 Trying to access JSON data as text without converting it first.

Wrong approach:

$json = '{"name":"Anna"}'
Write-Output $json.Name # This returns nothing or error

Correct approach:

$json = '{"name":"Anna"}'
$obj = $json | ConvertFrom-Json
Write-Output $obj.Name # Outputs 'Anna'

Root cause:

Not understanding that JSON text must be converted to objects before accessing properties.

#2 Not setting -Depth when converting complex nested objects to JSON.

Wrong approach:

$obj = [PSCustomObject]@{User=@{Name='Ben'; Info=@{City='LA'}}}
$json = $obj | ConvertTo-Json
Write-Output $json # Nested Info may be missing

Correct approach:

$obj = [PSCustomObject]@{User=@{Name='Ben'; Info=@{City='LA'}}}
$json = $obj | ConvertTo-Json -Depth 3
Write-Output $json # Full nested data included

Root cause:

Assuming default depth includes all nested data, leading to incomplete JSON output.

#3 Using ConvertFrom-Json on very large JSON files without considering memory use.

Wrong approach:

Get-Content largefile.json | ConvertFrom-Json # May cause memory issues

Correct approach:

Use streaming JSON parsers or process file in chunks instead of loading all at once.

Root cause:

Not realizing ConvertFrom-Json loads entire JSON into memory, causing performance problems.

Key Takeaways

ConvertFrom-Json and ConvertTo-Json are essential PowerShell commands to switch between JSON text and objects.

JSON text is a string format, while PowerShell objects let you easily access and manipulate data.

Always remember to set the -Depth parameter in ConvertTo-Json to include nested data fully.

Be cautious with very large JSON files as these commands load all data into memory, which can slow or crash scripts.

Understanding these commands unlocks powerful automation and integration capabilities with APIs and data formats.