Track YAML 1.2.2 gap backlog and PowerShell API design alignment

[MariusStorhaug]

Context

The spec folder now captures YAML 1.2.2 conformance gaps and capability backlog items that need implementation issues. These items should be delivered in a way that fits idiomatic PowerShell: rich objects, predictable pipeline behavior, and clear parameter sets that separate projection, parsing, formatting, and compatibility modes.

Official YAML 1.2.2 reference:

• https://yaml.org/spec/1.2.2/
• Repository copy: docs/yaml-spec-1.2.2/
• Module spec folder: spec/README.md

Current State

Several YAML behaviors are already implemented or partially implemented. Existing open issues also cover some related areas, especially timestamp parsing, presentation/comment preservation, and representation-preserving entry removal. The newly created issues split the remaining gaps into focused delivery leaves.

Objective

Track the YAML 1.2.2 gap backlog and keep related issues aligned so implementation work can proceed in small, focused slices without duplicating scope.

Backlog Map

Conformance and safety

• Implement YAML 1.2.2 byte-pattern encoding detection #56 — Implement YAML 1.2.2 byte-pattern encoding detection
• Align YAML directive handling with YAML 1.2.2 #57 — Align YAML directive handling with YAML 1.2.2
• Reject invalid local and global YAML tag text #58 — Reject invalid local and global YAML tag text
• Document and verify representation key uniqueness across stream surfaces #59 — Document and verify representation key uniqueness across stream surfaces
• Codify safe unknown YAML tag handling #60 — Codify safe unknown YAML tag handling

Schema and tag extensibility

• Add schema selection for core, JSON, and failsafe YAML schemas #61 — Add schema selection for core, JSON, and failsafe YAML schemas
• Add opt-in tag and scalar resolvers #62 — Add opt-in tag and scalar resolvers
• Support timestamp parsing #23 — Support timestamp parsing; align as explicit timestamp construction or opt-in resolver/schema behavior, not YAML 1.2 core implicit resolution

Emission and presentation

• Add YAML emission presentation controls #63 — Add YAML emission presentation controls
• Add YAML emission value policy controls #64 — Add YAML emission value policy controls
• Add opt-in YAML presentation metadata model #65 — Add opt-in YAML presentation metadata model
• Preserve comments through ConvertFrom-Yaml/ConvertTo-Yaml round-trip #28 — Preserve comments through ConvertFrom-Yaml/ConvertTo-Yaml round-trip; treat as a delivery slice of Add opt-in YAML presentation metadata model #65

YAML 1.1 compatibility and representation-preserving operations

• Add opt-in YAML merge key resolution #66 — Add opt-in YAML merge key resolution
• Add representation-preserving YAML entry removal #44 — Add representation-preserving YAML entry removal; align with representation graph, unknown-tag, document selection, and merge-key semantics

PowerShell projection and command surface

• Add unordered hashtable projection mode #67 — Add unordered hashtable projection mode
• Add single-document selection for YAML streams #68 — Add single-document selection for YAML streams
• Add typed PowerShell object projection #69 — Add typed PowerShell object projection
• Add short aliases for YAML conversion commands #70 — Add short aliases for YAML conversion commands

PowerShell Design Principles

• Prefer explicit parameters over hidden behavior changes.
• Use parameter sets to make projection modes and incompatible output modes discoverable.
• Preserve current defaults unless a conformance correction or major-version breaking change is explicitly declared.
• Keep rich object output useful while rejecting YAML representations that would otherwise lose data silently.
• Keep ConvertFrom-Yaml/Import-Yaml parameter symmetry and ConvertTo-Yaml/Export-Yaml parameter symmetry.
• Keep Test-Yaml Boolean and pipeline-friendly while surfacing warnings through normal PowerShell warning streams.
• Use classified error identifiers for automation.

Acceptance Criteria

• Each linked issue has a clear YAML 1.2.2 reference or PowerShell command-surface rationale.
• Existing overlapping issues are linked to the new focused issues rather than duplicated.
• Implementation PRs can close one delivery leaf at a time.
• Breaking changes are explicitly marked and scoped.

Related

• spec/README.md
• YAML 1.2.2: https://yaml.org/spec/1.2.2/