5.6 KiB
ADR 0007: Use native YAML and ordered documents for inspection reports
Status
Proposed
Date
2026-10-06
Context
ConfigKit and PromptKit provide native YAML configuration inspection. Reusing their writers preserves captured value semantics, ordering, and redaction. YAML also supports automated consumption of structured reports.
The agreed initial direction is YAML-based structured inspection with JSON
deferred, and separate native documents for config show --scope all. The
remaining choices concern report defaults, document framing, and when output
begins relative to configuration loading.
Decision
The initial standard uses text for concise operator reports and YAML for structured consumption. JSON retains deferred status; a future format extension is evaluated against a concrete consumer need.
| Operation | Default report | Available initial formats |
|---|---|---|
help |
Text | Text |
version |
Text | Text, YAML |
config scopes, validate, sources, explain, diff |
Text | Text, YAML |
config show |
Native YAML | YAML |
promptkit list/show |
Text | Text, YAML |
These format choices govern initial configuration and PromptKit reports and version reporting. Additional families select formats appropriate to their own resources through their command contracts. Custom handler formats remain application-owned. Version format selection preserves the selected subject under ADR 0004.
Operations with a format choice use --format text|yaml. Format names are
lowercase. YAML-only display uses its native writer directly. Help presents its
registered text form. Format validation follows the usage outcome policy in
ADR 0005.
A single-scope config show writes the owning library's complete native redacted
YAML. Its output consists of the inspection document itself. The native writer
preserves effective presence, null and container distinctions, stable mapping
order, and sequence order according to its public contract.
config show --scope all emits one native document per registered scope in the
order defined by ADR 0009: application first,
PromptKit next when registered, followed by additional scopes in identifier order.
Each document begins with --- and a # scope: NAME comment. A one-scope all
selection uses the same labeled document form.
CommandKit writes the separators and comments around the native writer output. Comments label scopes for operators; document order follows the registered scope inventory. That framing offers callers an association between documents and scopes. Each scope retains its own value namespace and native rendering. The combined stream is an inspection report whose documents can be decoded individually.
CommandKit checks operation availability for selected scopes before acquisition. It acquires their views and completes validation required by those provider contracts before report output begins. A failure returns its diagnostic outcome before report writing. After writing begins, a writer failure may leave partial bytes and returns operational failure under ADR 0005.
Other structured reports use operation-specific YAML schemas and selection metadata. They contain one document and a trailing newline. Native explanation snapshots retain their safe YAML text and presence/redaction metadata when projected into structured reports. The CLI reference owns exact schemas and field names after implementation.
Report confidentiality follows the owning libraries' sensitivity classifications. Their safe writers and records supply redacted content. CommandKit preserves those confidentiality semantics; arbitrary caller content retains the caller's disclosure policy. Report delivery uses the supplied streams and the channel policy in ADR 0005. Configuration path syntax follows ConfigKit's JSON Pointer contract independently of serialization format.
Alternatives considered
| Alternative | Analysis |
|---|---|
| A scope-keyed YAML wrapper | Carries scope identity as parsed mapping keys. Rendering needs an additional wrapper representation and indentation of native documents. |
| JSON alongside YAML initially | Serves JSON-specific tools. The library maintains another serializer and representation contract. |
| YAML as every report's default | Provides uniform structured output. Interactive help, tables, and explanation workflows use structured documents for routine discovery. |
| Output each scope as acquisition finishes | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. |
| Marshal application runtime structs | Reuses application data types. Presence, captured resolution, ordering, and safe historical inspection need a separate rendering lifecycle. |
Consequences
Native display preserves owning-library behavior and keeps rendering focused. Combined inspection requires multi-document YAML consumption and an ordered scope contract. The comments label documents, and the ordered inventory supports identification.
Loading all scopes before output adds preparation time and allows a failure in one selected scope to prevent combined output. Explicit single-scope inspection remains available for a narrower view. Writer failures remain visible through outcomes and may leave partial output.
Additional structured schemas are compatibility contracts owned by CommandKit. Native concatenation can use existing writers; semantic comparison separately requires the safe structured data described in ADR 0011.