- Reference
- Module:
- Microsoft.PowerShell.Utility
Converts a JSON-formatted string to a custom object or a hash table.
Syntax
ConvertFrom-Json [-InputObject] <String> [-AsHashtable] [-Depth <Int32>] [-NoEnumerate] [<CommonParameters>] Description
The ConvertFrom-Json cmdlet converts a JavaScript Object Notation (JSON) formatted string to acustom PSObject or Hashtable object that has a property for each field in the JSON string.JSON is commonly used by web sites to provide a textual representation of objects. The cmdlet addsthe properties to the new object as it processes each line of the JSON string.
The JSON standard allows duplicate key names, which are prohibited in PSObject and Hashtabletypes. For example, if the JSON string contains duplicate keys, only the last key is used by thiscmdlet. See other examples below.
To generate a JSON string from any object, use the ConvertTo-Json cmdlet.
This cmdlet was introduced in PowerShell 3.0.
Note
Beginning with PowerShell 6, the cmdlet supports JSON with comments. JSON comments start with twoforward slashes (//) characters. JSON comments aren't captured in the objects output by thecmdlet. Prior to PowerShell 6, ConvertFrom-Json would return an error when it encountered a JSONcomment.
Examples
Example 1: Convert a DateTime object to a JSON object
This command uses the ConvertTo-Json and ConvertFrom-Json cmdlets to convert a DateTimeobject from the Get-Date cmdlet to a JSON object then to a PSCustomObject.
Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-JsonDisplayHint : 2DateTime : Friday, January 13, 2012 8:06:31 PMDate : 1/13/2012 8:00:00 AMDay : 13DayOfWeek : 5DayOfYear : 13Hour : 20Kind : 2Millisecond : 400Minute : 6Month : 1Second : 31Ticks : 634620819914009002TimeOfDay : @{Ticks=723914009002; Days=0; Hours=20; Milliseconds=400; Minutes=6; Seconds=31; TotalDays=0.83786343634490734; TotalHours=20.108722472277776; TotalMilliseconds=72391400.900200009; TotalMinutes=1206.5233483366667;TotalSeconds=72391.4009002}Year : 2012The example uses the Select-Object cmdlet to get all of the properties of the DateTimeobject. It uses the ConvertTo-Json cmdlet to convert the DateTime object to a stringformatted as a JSON object and the ConvertFrom-Json cmdlet to convert the JSON-formatted stringto a PSCustomObject object.
Example 2: Get JSON strings from a web service and convert them to PowerShell objects
This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web serviceand then it uses the ConvertFrom-Json cmdlet to convert JSON content to objectsthat can be managed in PowerShell.
# Ensures that Invoke-WebRequest uses TLS 1.2[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-JsonYou can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content toobjects.
Example 3: Convert a JSON string to a custom object
This example shows how to use the ConvertFrom-Json cmdlet to convert a JSON file to a PowerShellcustom object.
Get-Content -Raw JsonFile.JSON | ConvertFrom-JsonThe command uses Get-Content cmdlet to get the strings in a JSON file. The Raw parameterreturns the whole file as a single JSON object. Then it uses the pipeline operator to send thedelimited string to the ConvertFrom-Json cmdlet, which converts it to a custom object.
Example 4: Convert a JSON string to a hash table
This command shows an example where the -AsHashtable switch can overcome limitations of thecommand.
'{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtableThe JSON string contains two key value pairs with keys that differ only in casing. Without theswitch, the command would have thrown an error.
Example 5: Round-trip a single element array
This command shows an example where the -NoEnumerate switch is used to round-trip a single elementJSON array.
Write-Output "With -NoEnumerate: $('[1]' | ConvertFrom-Json -NoEnumerate | ConvertTo-Json -Compress)"Write-Output "Without -NoEnumerate: $('[1]' | ConvertFrom-Json | ConvertTo-Json -Compress)"With -NoEnumerate: [1]Without -NoEnumerate: 1The JSON string contains an array with a single element. Without the switch, converting the JSON toa PSObject and then converting it back with the ConvertTo-Json command results in a singleinteger.
Parameters
-AsHashtable
Converts the JSON to a hash table object. This switch was introduced in PowerShell 6.0. Startingwith PowerShell 7.3, the object is an OrderedHashtable and preserves the ordering of the keysfrom the JSON. In prior versions, the object is a Hashtable.
There are several scenarios where it can overcome some limitations of the ConvertFrom-Json cmdlet.
- Without this switch, when two or more keys in a JSON object are case-insensitively identical, theyare treated as identical keys. In that case, only the last of those case-insensitively identicalkeys is included in the converted object.
- Without this switch, the cmdlet throws an error whenever the JSON contains a key that's an emptystring. PSCustomObject can't have property names that are empty strings. For example, this canoccur in
project.lock.jsonfiles. - Hash tables can be processed faster for certain data structures.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Depth
Gets or sets the maximum depth the JSON input is allowed to have. The default is 1024.
This parameter was introduced in PowerShell 6.2.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InputObject
Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string,or type a command or expression that gets the string. You can also pipe a string toConvertFrom-Json.
The InputObject parameter is required, but its value can be an empty string. When the inputobject is an empty string, ConvertFrom-Json doesn't generate any output. The InputObjectvalue can't be $null.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-NoEnumerate
Specifies that output isn't enumerated.
Setting this parameter causes arrays to be sent as a single object instead of sending every elementseparately. This guarantees that JSON can be round-tripped via ConvertTo-Json.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
String
You can pipe a JSON string to ConvertFrom-Json.
Outputs
PSCustomObject
OrderedHashtable
Notes
This cmdlet is implemented using Newtonsoft Json.NET.
Beginning in PowerShell 6, ConvertTo-Json attempts to convert strings formatted as timestamps toDateTime values. The converted value is a [datetime] instance with a Kind property set asfollows:
Unspecified, if there is no time zone information in the input string.Utc, if the time zone information is a trailingZ.Local, if the time zone information is given as a trailing UTC offset like+02:00. Theoffset is properly converted to the caller's configured time zone. The default output formattingdoesn't indicate the original time zone offset.
The PSObject type maintains the order of the properties as presented in the JSON string.Beginning with PowerShell 7.3, The AsHashtable parameter creates an OrderedHashtable. Thekey-value pairs are added in the order presented in the JSON string. The OrderedHashtablepreserves that order.
- An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET
- ConvertTo-Json
- Invoke-WebRequest
- Invoke-RestMethod
