Design Document: Built-in resources
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 523
- Forks
- 75
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 24
Description
We need to define some design principles for built-in resources so we can ensure that the resources that ship with DSC follow best practices and provide first-class ergonomics to users. The built-in resources serve both as examples for resource design and will be among the most-used resources.
During the review for the 3.2 GA, I noticed a few specific design principles we should call out. The following list is non-exhaustive:
- Only define the
_existcanonical property at the top-level for a resource instance JSON Schema and only when the resource can both create and delete instances. The resource must implement the canonical property in adherence to the contract. Don't define_existfor nested instances of a*Listresource, since those instances can't participate in the engine semantics for existence. - When a resource has the
_existcanonical property it should implement theget,set,export, anddeleteoperations. - Always implement what-if support for
setanddeleteoperations. - Always return all non-write-only properties for the actual state of a resource if those property values are knowable. If the values are not knowable for a given operation, omit those properties from the return data. In JSON Schema defining a property as
nulland omitting the property are semantically distinct representations of data. Only populate a field withnullwhen that actually matches the underlying resource behavior (when the resource has a nullable property, rather than an unset or undiscoverable property value). - Always mark properties that can be passed to but not returned by the resource with the
writeOnlykeyword. - Always mark properties that can be returned by but not passed to the resource with the
readOnlykeyword. - Never add
nullas a valid value for a property in the instance JSON Schema whennullindicates that you aren't passing a value for the property. Only allownullfor properties wherenullis a valid value for that property. - When creating a
*Listresource to manage multiple instances, also be sure to create a companion resource that manages a single instance. We should direct users towards the*Listresource options only when the performance impact for single instances is too high. Those resources are much less ergonomic for result output and are somewhat obfuscated in the node graph. Using those resources necessitates tradeoffs in ergonomics for authoring vs reporting and performance vs clarity.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No file, test, or entry point is named in the issue. Define and document the design principles for built-in resources, including the listed schema, operation, what-if, property, nullability, and companion-resource requirements; done means the principles are recorded as an agreed design document.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100