Spec: structured output for WinGet CLI

[Przemysław Kłys (PrzemyslawKlys)]

Description

Define opt-in structured output for installed-package and available-upgrade listings, with one shared invocation envelope for results, contextual warnings, and the final invocation error.

This revision follows the design review: it preserves installed and available package relationships, separates installed and upgrade provenance, records canonical arguments, uses integer HRESULTs and open diagnostic identifiers, and defaults to compact JSON. Schema versions follow the shipping client, and output-format telemetry extends the existing event.

The specification remains a draft pending agreement on the contract and its maintenance cost. #6536 must be updated to the agreed contract before it can be considered ready. #6346 is the earlier implementation under discussion.

AI assistance: OpenAI Codex assisted with the specification and this revision.

Related Issues

• JSON Formatted Output Support #184
• Add JSON format for list outputs #6346
• Add experimental structured CLI output #6536

Validation

All six JSON examples parse successfully. No executable code changes in this PR.

Checklist

• Signed the Contributor License Agreement
• Linked to the tracking issue
• Design reviewed and agreed

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Przemysław Kłys (PrzemyslawKlys)]

I've now opened #6536 as the draft implementation of this proposal. It stays behind the experimental feature, and I'll keep it aligned with any changes we make here. The implementation branch currently includes the spec commits because GitHub cannot base a PR in this repository on a branch that exists only in a fork; once this spec lands, I'll rebase it to an implementation-only diff.

[JohnMcPMS]

The biggest reason not to do this is that it is one more contract we have to maintain (when we already have many). COM is really the best model, but PowerShell is pretty similar. And both are a bit behind the internal model in terms of the real structure, although they can theoretically express the full fidelity (PowerShell is also behind COM usually).