external help file | Locale | Module Name | ms.date | online version | schema | title |
---|---|---|---|---|---|---|
Microsoft.PowerShell.Commands.Utility.dll-Help.xml |
en-US |
Microsoft.PowerShell.Utility |
03/14/2024 |
2.0.0 |
Test-Json |
Tests whether a string is a valid JSON document
Test-Json [-Json] <String> [<CommonParameters>]
Test-Json [-Json] <string> [-Schema] <string> [<CommonParameters>]
Test-Json [-Json] <string> [-SchemaFile] <string> [<CommonParameters>]
Test-Json [-Path] <string> [<CommonParameters>]
Test-Json [-Path] <string> [-Schema] <string> [<CommonParameters>]
Test-Json [-Path] <string> [-SchemaFile] <string> [<CommonParameters>]
Test-Json [-LiteralPath] <string> [<CommonParameters>]
Test-Json [-LiteralPath] <string> [-Schema] <string> [<CommonParameters>]
Test-Json [-LiteralPath] <string> [-SchemaFile] <string> [<CommonParameters>]
The Test-Json
cmdlet tests whether a string is a valid JavaScript Object Notation (JSON) document
and can optionally verify that JSON document against a provided schema.
The verified string can then be used with the ConvertFrom-Json
cmdlet convert a JSON-formatted
string to a JSON object, which is easily managed in PowerShell or sent to another program or web
service that access JSON input.
Many web sites use JSON instead of XML to serialize data for communication between servers and web-based apps.
This cmdlet was introduced in PowerShell 6.1
This example tests whether the input string is a valid JSON document.
'{"name": "Ashley", "age": 25}' | Test-Json
True
This example takes a string containing a JSON schema and compares it to an input string.
$schema = @'
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/root.json",
"type": "object",
"title": "The Root Schema",
"required": [
"name",
"age"
],
"properties": {
"name": {
"$id": "#/properties/name",
"type": "string",
"title": "The Name Schema",
"default": "",
"examples": [
"Ashley"
],
"pattern": "^(.*)$"
},
"age": {
"$id": "#/properties/age",
"type": "integer",
"title": "The Age Schema",
"default": 0,
"examples": [
25
]
}
}
}
'@
'{"name": "Ashley", "age": "25"}' | Test-Json -Schema $schema
Test-Json:
Line |
35 | '{"name": "Ashley", "age": "25"}' | Test-Json -Schema $schema
| ~~~~~~~~~~~~~~~~~~~~~~~~~
| The JSON is not valid with the schema: Value is "string" but should be "integer" at '/age'
False
In this example, we get an error because the schema expects an integer for age but the JSON input we tested uses a string value instead.
For more information, see JSON Schema.
JSON schema can reference definitions using $ref
keyword. The $ref
can resolve to a URI that
references another file. The SchemaFile parameter accepts literal path to the JSON schema file
and allows JSON files to be validated against such schemas.
In this example the schema.json
file references definitions.json
.
Get-Content schema.json
{
"description":"A person",
"type":"object",
"properties":{
"name":{
"$ref":"definitions.json#/definitions/name"
},
"hobbies":{
"$ref":"definitions.json#/definitions/hobbies"
}
}
}
Get-Content definitions.json
{
"definitions":{
"name":{
"type":"string"
},
"hobbies":{
"type":"array",
"items":{
"type":"string"
}
}
}
}
'{"name": "James", "hobbies": [".NET", "Blogging"]}' | Test-Json -SchemaFile 'schema.json'
True
For more information, see Structuring a complex schema.
Specifies the JSON string to test for validity. Enter a variable that contains the string, or type a
command or expression that gets the string. You can also pipe a string to Test-Json
.
The Json parameter is required.
Type: System.String
Parameter Sets: JsonString, JsonStringWithSchemaString, JsonStringWithSchemaFile
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
Specifies a path to a JSON file. The value of LiteralPath is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences.
This parameter was added in PowerShell 7.4.
Type: System.String
Parameter Sets: JsonLiteralPath, JsonLiteralPathWithSchemaString, JsonLiteralPathWithSchemaFile
Aliases: PSPath, LP
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Specifies the path to a JSON file. This cmdlet gets the item at the specified location. Wildcard characters are permitted but the pattern must resolve to a single file.
This parameter was added in PowerShell 7.4.
Type: System.String
Parameter Sets: JsonPath, JsonPathWithSchemaString, JsonPathWithSchemaFile
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True
Specifies a schema to validate the JSON input against. If passed, Test-Json
validates that the
JSON input conforms to the spec specified by the Schema parameter and return $true
only if the
input conforms to the provided schema.
For more information, see JSON Schema.
Type: System.String
Parameter Sets: JsonStringWithSchemaString, JsonLiteralPathWithSchemaString, JsonPathWithSchemaString
Aliases:
Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Specifies a schema file used to validate the JSON input. When used, the Test-Json
returns $true
only if the JSON input conforms to the schema defined in the file specified by the SchemaFile
parameter.
For more information, see JSON Schema.
Type: System.String
Parameter Sets: JsonStringWithSchemaFile, JsonLiteralPathWithSchemaFile, JsonPathWithSchemaFile
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
You can pipe a JSON string to this cmdlet.
This cmdlet returns $true
if the JSON is valid and otherwise $false
.
Since PowerShell 6, PowerShell uses the Newtonsoft.Json assemblies for JSON functions. Newtonsoft's implementation includes several extensions to the JSON standard, such as support for comments and use of single quotes. For a full list of features, see the Newtonsoft documentation at https://www.newtonsoft.com/json.
Beginning in PowerShell 7.4, Test-Json
uses System.Text.Json for JSON
parsing and JsonSchema.NET for schema validation.
With these changes, Test-Json
:
- No longer supports Draft 4 schemas
- Only supports strictly conformant JSON
For a complete list of differences between Newtonsoft.Json and System.Text.Json, see the Table of differences in Migrate from Newtonsoft.Json to System.Text.Json.
For more information about JSON schema specifications, see the documentation at JSON-Schema.org.
An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET