DSC should populate the `desiredState` blob with non-specified default values

[michaeltlombardi]

Summary of the new feature / enhancement

Important

Bottom line up front, I propose that DSC should "fill in" the default values for an instance immediately before or after validating it against the schema that applies to the instance and treat that merged blob as canonical for both messaging and operations.

Context

From verbal discussion, the point was raised that when a user doesn't explicitly define an instance property, the results for the test operation may be confusing when the actual state of an instance doesn't match the desired state.

For example, should this result have _inDesiredState set to true or false?

desiredState:
  path: /etc/xdg/TailSpinToys/tstoy/tstoy.config.json
actualState:
  path: /etc/xdg/TailSpinToys/tstoy/tstoy.config.json
  _exist: false

In this case, it should be false, because the file is expected to exist and doesn't - _exist has a default value of true.

Normally, for _exist, you'd also have other properties defined that would help you see what was wrong. But if we consider a resource with a property updateFrequency defined as with this subschema:

{
    "title": "Update check frequency",
    "description": "Indicates how many days TSToy should wait before checking for updates.",
    "type": "integer",
    "minimum": 1,
    "maximum": 90,
    "default": 30
}

We would expect that the following instance is not in the desired state:

desiredState:
  scope:               machine
  updateAutomatically: true
actualState:
  scope:               machine
  updateAutomatically: true
  updateFrequency:     15

We should more clearly distinguish for authors and users between the default value of a property for an underlying system or component that a resource manages and whether a resource declares a default value for an instance property in its schema.

These are not the same.

Semantically:

• If a property is not required and doesn't have a default value, users should be able to expect that not specifying the property doesn't have an affect on getting, testing, or setting the instance.
• If a property is not required and does have a default value, users should be able to expect that the default value is used when they don't specify it for the instance when getting, testing, or setting the instance.
• If a property is explicitly specified, users should be able to expect that the value they defined is used when getting, testing, or setting the instance.

Proposed technical implementation details (optional)

After DSC validates an input instance in a configuration document or for direct invocation, it has access to the schema for that instance. Either before or after that validation¹, DSC could modify the input blob to add any non-specified properties with their default values. It should only add properties to the blob, not modify existing ones.

This would ensure that the synthetic testing, messaging, and invocation operations all include the explicit model of the instance state instead of implying the defaults. This has a few benefits:

• Authoring and invoking resource instances is still low-effort - you're not required to define properties with default values unless you intend to override them. This is the same UX/DevX as we have now.
• Comparing desired state to actual state or changed state is easier - you can see the full, explicit definition of an instance directly in the output.
• Synthetic testing can operate on default values without special handling.
• While the implementation of the resource and its instance schema may drift, users can treat the schema definition as canonical, because this model explicitly passes the defined default value, even if the implementation changes that default internally and doesn't update the schema.
• This model clarifies the distinction between instance properties with a default value and those without one, especially in the output data.

Footnotes

1. One reason to insert the default values before validation is that, technically, default values aren't required by JSON schema to validate against the property subschema. JSON Schema doesn't raise a validation error if you define the default value for a string property as 5 or false or ['a', 'b']. If the default is inserted before validation, those kinds of errors can be caught and surfaced before taking any other action with the resource instance. ↩