[Feature] `export` should accept JSON arrays as well as JSONL

[EmperorArthur]

Summary of the new feature / enhancement

As someone who just created their first resource, I expected the export option to accept a simple JSON array. It took me way too long to find the correct documentation and realize I needed to write an adapter.

Note, this is separate from: #1232

Example of a command which should not require a separate program just to re-parse JSON:

python -m pip --no-input list --format=json

Proposed technical implementation details (optional)

DSC should dynamically determine if said output is a JSON array or in JSONL format.

This can be done by examining the first non-white space character returned.

• If it is [ the output is an array of objects. Each object matching the existing schema.
• If it is { the output is in JSONL format.

[michaeltlombardi]

We standardized on emitting JSON Lines across all resource operations. DSC parses the stdout line by line. DSC can emit final data as JSON Lines, pretty JSON, and YAML, but it requires resources to emit JSON Lines to simplify stream processing emitted data from resources. This also applies to messages emitted to stderr.

[EmperorArthur]

I can see your point. Especially when it comes to efficiency in the general case. However, python -m pip --no-input list --format=json does emit a single JSON line. It just happens to be an array of objects.

While my original proposal was a more general case, you could also perform the check once the JSON has been ingested.

[michaeltlombardi]

That would require the check and varied processing on every emitted object for every operation (in the current implementation, the resource invocation method is generic). From within the resource implementation, I would expect that the resource does some amount of processing before emission - in fact, to support some features, the resource has to (like the new functionality for inserting the _name property to hoist for the instance name during export) do so.

I'm not sure I see a benefit to the loss of deterministic contract. If we were to implement such a feature, I would expect that it be advertised with a resource manifest field to avoid the ambiguity and dynamic checking.

[EmperorArthur]

Perfectly understandable to have the expected output defined in the manifest, rather than dynamically determined. The ability for export to accept a JSON array is what I am focused on, and not any specific implementation.

This proposal, and the others I made, is about handling common scenarios presented by existing package managers. Without every implementer having to do the same thing in a different way. I understand the tightrope of wanting this to be useful and functional, while also not bloating bloating the core runtime with features.

Alternative Implementation Option

Please consider this more as a brainstorming idea, and not let it influence your decision on the feature itself.

Add an additional property to export.manifest.json.

"output": {
  "$ref": "/PowerShell/DSC/main/schemas/v3/definitions/outputKind.json"
}

"/PowerShell/DSC/main/schemas/v3/definitions/outputKind.json": {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "/PowerShell/DSC/main/schemas/v3/definitions/outputKind.json",
  "title": "Executable Command Output Type",
  "description": "Defines the format DSC should expect the command to output, either as JSONL, or a JSON array.",
  "type": "string",
  "default": "jsonl",
  "enum": [
    "jsonl",
    "array"
  ]
}