docs: Update shared definitions and Microsoft.DSC metadata reference

[Gijs Reijn (Gijsreyn)]

PR Summary

As requested, shortened the number of files and updated it based on separate schema groups.

PR context

Synced docs from Microsoft Learn: MicrosoftDocs/PowerShell-Docs-DSC#414

[Copilot]

🟡 Changes recommended

Multiple updated docs diverge from (or reference missing) schema artifacts in this repo, creating broken/unverifiable schema contracts.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates several DSC schema reference docs (synced from Microsoft Learn) to reflect newer schema groupings and refreshed metadata, type-name, capability, and function/type definitions documentation.

Changes:

• Refreshes Microsoft.DSC metadata property reference content (including new restart/copy-loop related documentation).
• Updates resource type-name pattern guidance and propagates the new pattern into related schema docs.
• Expands resource capabilities and function data-type schema reference docs with additional explanatory content.

File summaries

File	Description
docs/reference/schemas/metadata/Microsoft.DSC/properties.md	Updates Microsoft.DSC metadata property reference and adds restart/copy-loop guidance.
docs/reference/schemas/definitions/resourceType.md	Revises the documented type-name pattern and explains namespace segmentation.
docs/reference/schemas/definitions/resourceKind.md	Reflows and updates examples/schema references for resource kind documentation.
docs/reference/schemas/definitions/resourceCapabilities.md	Updates documented resource capability values and adds a manifest-to-capability mapping table.
docs/reference/schemas/definitions/parameters/dataTypes.md	Updates parameter data type casing and clarifies case sensitivity.
docs/reference/schemas/definitions/message.md	Adds description context and updates documented resource type-name pattern usage.
docs/reference/schemas/definitions/functions/builtin/dataTypes.md	Updates function data types schema reference metadata and adds context about where types appear in output.

Review details

Suppressed comments (2)

docs/reference/schemas/definitions/resourceCapabilities.md:55

• The capability descriptions list setWhatIf and deleteWhatIf, but the referenced v3.1.0 schema only defines a single whatIf capability (and no delete simulation capability). The bullets should align with the schema this page documents.

- `setWhatIf` - The resource supports simulating the **Set** operation directly, reporting how it
  would change the state of an instance without changing it. This capability was added in DSC
  version 3.3.0. Through DSC version 3.2.x, this capability was reported as `whatIf`.
- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing.
- `delete` - The resource supports removing an instance.
- `deleteWhatIf` - The resource supports simulating the **Delete** operation directly, reporting
  how it would remove an instance without removing it. This capability was added in DSC version
  3.3.0.

docs/reference/schemas/definitions/resourceType.md:59

• This page is scoped to the v3.1.0 schema, but the text claims the number of namespace segments is unlimited starting with DSC 3.2.0; there is no corresponding schema version in this repo, and the v3/v3.1 schemas still enforce a maximum segment count. This statement should be removed or moved to versioned docs that include the updated schema.

Earlier versions of the schema limited the number of namespace segments. The schemas published for
DSC 3.0 allow up to three segments and the schemas published for DSC 3.1 allow up to four. Starting
with DSC 3.2.0, the number of segments is unlimited.

• Files reviewed: 7/7 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Mikey Lombardi (He/Him) (michaeltlombardi)]

This represents a bug in the dsc_repo_schema attribute on functions::FunctionArgKind - we can't change the ID for the public schema between minor/patch releases without significant extra work (functionally turning the original into an alias and writing it as a one-key schema like $ref: <new_id>).

Instead, we should revert the ID change to .../dataTypes.json.

[Gijs Reijn (Gijsreyn)]

Done! Should we add an issue to track it?