Align scalar resolution with YAML 1.2.2 core schema (case-sensitive true/false/null)

Author: MariusStorhaug

README.md

@@ -5,6 +5,7 @@
 ## Prerequisites
 
 This uses the following external resources:
+
 - The [PSModule framework](https://github.com/PSModule) for building, testing and publishing the module.
 
 ## Installation
@@ -25,6 +26,19 @@ The module provides two cmdlets that mirror PowerShell's built-in `ConvertFrom-J
 | `ConvertFrom-Yaml`  | `ConvertFrom-Yml` | Parse a YAML string into an object.   |
 | `ConvertTo-Yaml`    | `ConvertTo-Yml`  | Serialize an object into a YAML string. |
 
+### YAML specification
+
+The module aligns with [**YAML 1.2.2**](https://yaml.org/spec/1.2.2/) (October 2021) — the latest revision of the YAML specification — and follows the [**core schema**](https://yaml.org/spec/1.2.2/#103-core-schema) for scalar resolution.
+
+Practical implications of the core schema:
+
+- `true` and `false` (lowercase only) parse as `[bool]`. `True`, `TRUE`, `yes`, `no`, `on`, `off`, etc. are plain strings.
+- `null`, `~`, and an empty value parse as `$null`. `Null`, `NULL` are plain strings.
+- Integers and floats parse to their native types using invariant culture.
+- Anything else is a string. Quoted strings (`'...'`, `"..."`) always preserve the string type.
+
+The supported YAML subset covers block-style mappings, block-style sequences, nested structures, single- and double-quoted scalars (with `\n`, `\t`, `\r`, `\\`, `\"` escapes in double quotes), and full-line / inline `#` comments. Flow style (`[a, b]`, `{a: 1}`), block scalars (`|`, `>`), anchors, aliases, tags, multi-document streams, and `!!timestamp` are not yet supported.
+
 ### Example 1: Parse a YAML string
 
 ```powershell

src/functions/private/ConvertFrom-YamlNode.ps1

@@ -232,16 +232,12 @@ function ConvertFrom-YamlScalar {
         return (Expand-YamlDoubleQuoted -Text $inner)
     }
 
-    # Null literals.
-    if ($value -in @('~', 'null', 'Null', 'NULL')) { return $null }
+    # Null literal (YAML 1.2.2 core schema): empty, ~, null only. Case-sensitive.
+    if ($value -ceq '~' -or $value -ceq 'null') { return $null }
 
-    # Boolean literals.
-    if ($value -in @('true', 'True', 'TRUE', 'yes', 'Yes', 'YES', 'on', 'On', 'ON')) {
-        return $true
-    }
-    if ($value -in @('false', 'False', 'FALSE', 'no', 'No', 'NO', 'off', 'Off', 'OFF')) {
-        return $false
-    }
+    # Boolean literal (YAML 1.2.2 core schema): true / false only. Case-sensitive.
+    if ($value -ceq 'true') { return $true }
+    if ($value -ceq 'false') { return $false }
 
     # Integer.
     $intVal = 0

src/functions/private/ConvertTo-YamlNode.ps1

@@ -407,18 +407,11 @@ function Test-YamlPlainSafe {
     if ($Text.Length -eq 0) { return $false }
     if ($Text -ne $Text.Trim()) { return $false }
 
-    # Strings that look like reserved literals must be quoted to preserve the string type.
-    $reserved = @(
-        'true', 'True', 'TRUE',
-        'false', 'False', 'FALSE',
-        'yes', 'Yes', 'YES',
-        'no', 'No', 'NO',
-        'on', 'On', 'ON',
-        'off', 'Off', 'OFF',
-        'null', 'Null', 'NULL',
-        '~'
-    )
-    if ($Text -in $reserved) { return $false }
+    # Strings that match YAML 1.2.2 core schema literals must be quoted to preserve string type.
+    # Comparison is case-sensitive — only the lowercase canonical forms are recognised by parsers.
+    if ($Text -ceq 'true' -or $Text -ceq 'false' -or $Text -ceq 'null' -or $Text -ceq '~') {
+        return $false
+    }
 
     # Strings that parse as a number must be quoted.
     $tmpInt = 0L

src/functions/public/ConvertFrom-Yaml.ps1

@@ -102,10 +102,10 @@
         }
 
         $context = [pscustomobject]@{
-            Lines      = $lines
-            Index      = 0
+            Lines       = $lines
+            Index       = 0
             AsHashtable = [bool] $AsHashtable
-            MaxDepth   = $Depth
+            MaxDepth    = $Depth
         }
 
         $result = ConvertFrom-YamlNode -Context $context -Indent 0 -Depth 0

tests/ConvertFrom-Yaml.Tests.ps1

@@ -29,18 +29,28 @@ Describe 'ConvertFrom-Yaml' {
             $result.ratio | Should -BeOfType [double]
         }
 
-        It 'Parses boolean true variants' {
-            $result = "a: true`nb: True`nc: yes" | ConvertFrom-Yaml
+        It 'Parses boolean true' {
+            $result = 'a: true' | ConvertFrom-Yaml
             $result.a | Should -BeTrue
-            $result.b | Should -BeTrue
-            $result.c | Should -BeTrue
+            $result.a | Should -BeOfType [bool]
         }
 
-        It 'Parses boolean false variants' {
-            $result = "a: false`nb: False`nc: no" | ConvertFrom-Yaml
+        It 'Parses boolean false' {
+            $result = 'a: false' | ConvertFrom-Yaml
             $result.a | Should -BeFalse
-            $result.b | Should -BeFalse
-            $result.c | Should -BeFalse
+            $result.a | Should -BeOfType [bool]
+        }
+
+        It 'Treats non-canonical boolean-like words as strings (YAML 1.2.2)' {
+            # YAML 1.2.2 core schema only recognizes lowercase true/false. Everything else is a string.
+            $result = "a: True`nb: TRUE`nc: yes`nd: No`ne: on`nf: OFF" | ConvertFrom-Yaml
+            $result.a | Should -Be 'True'
+            $result.a | Should -BeOfType [string]
+            $result.b | Should -Be 'TRUE'
+            $result.c | Should -Be 'yes'
+            $result.d | Should -Be 'No'
+            $result.e | Should -Be 'on'
+            $result.f | Should -Be 'OFF'
         }
 
         It 'Parses null values' {
@@ -50,6 +60,13 @@ Describe 'ConvertFrom-Yaml' {
             $result.c | Should -BeNullOrEmpty
         }
 
+        It 'Treats non-canonical null-like words as strings (YAML 1.2.2)' {
+            $result = "a: Null`nb: NULL" | ConvertFrom-Yaml
+            $result.a | Should -Be 'Null'
+            $result.a | Should -BeOfType [string]
+            $result.b | Should -Be 'NULL'
+        }
+
         It 'Parses single-quoted strings preserving content' {
             $result = "value: 'true'" | ConvertFrom-Yaml
             $result.value | Should -Be 'true'

tests/ConvertTo-Yaml.Tests.ps1

@@ -62,15 +62,15 @@ Describe 'ConvertTo-Yaml' {
     Context 'Mappings' {
         It 'Renders a flat hashtable' {
             $yaml = ([ordered]@{ name = 'Alice'; age = 30 }) | ConvertTo-Yaml
-            $lines = $yaml.TrimEnd("`r","`n") -split "`r?`n"
+            $lines = $yaml.TrimEnd("`r", "`n") -split "`r?`n"
             $lines[0] | Should -Be 'name: Alice'
             $lines[1] | Should -Be 'age: 30'
         }
 
         It 'Renders nested mappings with 2-space indent by default' {
             $obj = [ordered]@{
                 person = [ordered]@{
-                    name = 'Alice'
+                    name    = 'Alice'
                     address = [ordered]@{
                         city = 'Oslo'
                     }
@@ -200,9 +200,9 @@ Describe 'Round-trip ConvertTo-Yaml | ConvertFrom-Yaml' {
     It 'Preserves a nested mapping' {
         $obj = [ordered]@{
             person = [ordered]@{
-                name = 'Alice'
+                name    = 'Alice'
                 address = [ordered]@{
-                    city = 'Oslo'
+                    city    = 'Oslo'
                     country = 'Norway'
                 }
             }