powershell-yaml Documentation

To ensure values are converted to the correct type (e.g., preventing a string like +40123 from being cast to an Int64), use explicit YAML tags. This module supports core schema tags and the !!timestamp tag.

$data = @"
aPhoneNumber: !!str +40123456789
aPhoneNrWithoutTags: +40123456789
"@
$obj = ConvertFrom-Yaml $data
# $obj.aPhoneNumber is a String
# $obj.aPhoneNrWithoutTags is an Int64

You can install the powershell-yaml module directly from the PowerShell Gallery using Install-Module.

Install-Module powershell-yaml

When a YAML string contains multiple documents separated by ---, use the -AllDocuments switch with ConvertFrom-Yaml. This returns an Object[] (array) where each element is the content of a document.

Note: The resulting array may not translate back to the exact same multi-document YAML structure if passed back through ConvertTo-Yaml.

$yaml = @"
---
doc1: value
---
doc2: value
"@
$obj = ConvertFrom-Yaml $yaml -AllDocuments
# $obj[0] contains the first document
# $obj[1] contains the second document

Use ConvertFrom-Yaml to deserialize YAML strings into PowerShell objects. For a single YAML document, the result is typically a Hashtable.

Import-Module powershell-yaml
$yaml = @"
anArray:
- 1
- 2
- 3
"
$obj = ConvertFrom-Yaml $yaml

To support YAML merge keys (using <<: *anchor), use the -UseMergingParser switch with ConvertFrom-Yaml.

Warning: Attempting to overwrite a key that already exists via a merge key will throw a duplicate key exception.

$mergingYaml = @"
---
default: &default
  value1: 1
  value2: 2
hoge:
  <<: *default
  value3: 3
"@

ConvertFrom-Yaml -Yaml $mergingYaml -UseMergingParser

Use ConvertTo-Yaml to serialize PowerShell objects (like Hashtables or Arrays) into YAML strings. By default, it uses Block style formatting.

Import-Module powershell-yaml
$yaml = ConvertTo-Yaml @{"hello"="world"; "anArray"=@(1,2,3); "nested"=@{"array"=@("this", "is", "an", "array")}}

You can generate a JSON-compatible string from a PowerShell object by using the -JsonCompatible switch with ConvertTo-Yaml. This produces a single-line string without indentation, suitable for JSON-like structures.

Import-Module powershell-yaml
$obj = ConvertFrom-Yaml $yaml
ConvertTo-Yaml -JsonCompatible $obj
# Or in one line:
ConvertFrom-Yaml $yaml | ConvertTo-Yaml -JsonCompatible

You can change the visual style of the generated YAML using the -Options parameter in ConvertTo-Yaml:

• UseFlowStyle: Outputs everything in Flow style (JSON-like braces/brackets).
• UseSequenceFlowStyle: Outputs sequences in Flow style but keeps other elements in Block style.
• WithIndentedSequences: Indents sequences within Block style (by default, sequences are not indented).

Note: These options are additive/combinable where applicable.

# Flow style
ConvertTo-Yaml $data -Options UseFlowStyle

# Sequence flow style
ConvertTo-Yaml $data -Options UseSequenceFlowStyle

# Indented sequences in block style
ConvertTo-Yaml $data -Options WithIndentedSequences