Using the DSC document schema outside of dsc.exe

[JohnMcPMS]

winget already exposes access to PowerShell DSC v2 via a file format not that dissimilar from the one used here. We are also moving to use the schema here in the future. This brings with it a problem though; users who are content to use only PowerShell DSC v2 resources should not be required to take a dependency on dsc.exe and they should not be required to embed all of their resources into a PowerShell group (although this could be a path to a document that can work across both).

While we could implement some heuristic methods to detect whether the resource types are PowerShell or dsc.exe resources, we definitely need to give the author/user the ability to specify that fact. While this could be done as an additional command line parameter, it would be more robust to be able to embed it into the DSC document.

This brings up the first discussion point: Should the document schema provide an explicit field to indicate the target processing environment for the document? I believe that at a minimum the answer here is dependent on whether dsc.exe would want to be aware of and participate in explicitly blocking non-dsc.exe targeting documents. I have no particular opinion on the answer here currently.

The alternative is to embed this information into a metadata field at the root of the document. Which brings up a more general question: Should components above dsc.exe use metadata for behavior alteration? For both yes and no, what should the standard practice be, as there will always be additional layers that want to add in behavior altering metadata. My initial thought is that it is acceptable to place behavior altering metadata into the metadata field, but it is worthwhile to place all of a component's metadata into a single object. This reduces the likelihood of name collisions and implicitly documents the source of/handler for the metadata item.

For example:

metadata:
  winget:
    processor: pwsh # (or something to indicate `dsc.exe`)
resources:
  - name: Example Name
    type: Example Type
    metadata:
      winget:
        repository: MyPrivateAzureArtifactsContainer

It may be desirable to have an object whose contents are explicitly for non-behavior altering data, such as author's notes, descriptions for use in display contexts, or authoring tools. If so, I would request that we have an alternative object whose contents are explicitly for components sitting above dsc.exe to store behavior altering data. The presence of this object could be used as a signal to dsc.exe that the configuration document is potentially meant for a higher level tool, rather than the explicit processing environment field mentioned above. An additional flag could be passed to ignore these, allowing the higher level tool to use the document unaltered rather than needing to remove them before calling into dsc.exe.

[SteveL-MSFT]

For DSC, the intent is NOT to special case (even PowerShell) unless really required. Putting more execution directives into the metadata basically creates a new config document dialect whereas the current use of PowerShellGroup makes the relationship explicit. dsc.exe provides standardized functionality independent of resources: logging, whatif, order, etc... and with specialized resources will enable running configurations where parts are in parallel, under different creds, etc...

A special path for PowerShell essentially creates two different communities within DSC.

[JohnMcPMS]

I think this is misunderstanding my questions (or maybe I just don't agree with the answer). The more generic question is: How should higher level components encode information that is not understood by dsc.exe into the configuration document?

Someone will build something on top of DSC, and they will want to have custom information that isn't needed by DSC but is important to their product. They are explicitly trying to create an expanded dialect in that case. The options for storing that information are:

1. In the existing metadata field
2. In a new field that is outside of the DSC schema
3. In another document

I don't think that this question can be avoided; it will happen and setting the best practices will make things smoother in the long run. I also don't think that option 3 is going to be acceptable enough of an answer in most cases, unless maybe if dsc.exe explicitly states that it will only consume the first document in a YAML stream...

The more specific question relates to our integration, specifically that I'm trying to provide access to the existing PowerShell DSC v2 implementation and the DSC v3 implementation using the same schema. Even if we drop the v2 implementation eventually, there is an interim period where we must support both. I would also argue that there is an indefinite period where we support the less typing option of v2 (not requiring nesting within a group), although with better authoring tools I could see that being less of an issue.

[SteveL-MSFT]

Sorry if I misunderstood your question. The metadata property with the exception of the Microsoft.DSC property within metadata is not interpreted by DSC at all and is expected to be used by end users and integrated products for their own purposes.