YAML output should use document separators

[JohnMcPMS]

Summary of the new feature / enhancement

YAML supports multiple documents in a single stream. However, the current YAML output separates "documents" only by an empty line. While this convention can work, it is fragile. Even built-in resources have "empty" lines in their descriptions (see Microsoft/OSInfo). Placing an explicit document separator between entries (such as those of dsc resource list) would allow parsing the output stream directly without the need to pre-process the documents into individual parts. It would also make the start of a new item much easier to find as a human reader.

Proposed technical implementation details (optional)

At a minimum, output a document start and end sequence for each "document" in the output. For a cleaner look, only output a document start sequence before each "document" after the first.

[SteveL-MSFT]

If I'm understanding the spec right, a --- at the start can be implied, so we just need to emit a --- at the end?

[JohnMcPMS]

A document start (---) is implied at the beginning of the stream and a document end (...) is implied at the end of the stream. Document end is also implied to proceed a document start if not present.

I would suggest emitting a document start before each object after the first rather than simply replacing the current blank line with ---. That way there is no empty document trailing at the end.

But all of this depends on whether YAML is just for human reading or is ever intended as a parsed output format. I'm assuming that the current rendering is using VT sequences for color and thus would need to have a way to disable that (either automatically or with parsable-yaml or something). Given that, simply putting a --- at the end would aid humans sufficiently to close this issue until parsing YAML is supported.

[SteveL-MSFT]

@JohnMcPMS , you bring up a good point, the current YAML output is only intended for humans as any redirection will, by default, result in JSON. Is there any example usage that results in multi YAML docs being in the output? Any configuration operation should result in just a single object.

[JohnMcPMS]

Is there any example usage that results in multi YAML docs being in the output? Any configuration operation should result in just a single object.

dsc resource list -o yaml

I would argue that each resource should be its own document, as each one results in repetitions of type, kind, etc. Attempting to parse the output (by copying it from the terminal for example), would result in an error as the keys in the implicit top level mapping will not be unique. Placing document starts before each resource object (all of them or just those after the first) would both create an easy visual break for human consumption and make the output parsable.