docs: Sync fixes from Microsoft Learn on schema reference

[Gijs Reijn (Gijsreyn)]

PR Summary

This pull request syncs the docs with the changes made on Microsoft Learn.

PR Context

MicrosoftDocs/PowerShell-Docs-DSC#414

[Copilot]

🟡 Changes recommended

Several updated schema references (notably function schema SchemaID/ItemsReference) point to paths that don’t exist under schemas/ in this repo, making the docs’ canonical schema URLs resolve to 404.

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

Pull request overview

This PR syncs the DSC schema reference documentation with updates from Microsoft Learn, primarily expanding/clarifying schema semantics, updating examples, and aligning terminology/capabilities across resource/extension/config docs.

Changes:

• Expanded and clarified schema reference pages (stdout schemas, manifest properties, capabilities, metadata/execution info).
• Updated many function reference pages (syntax formatting, examples, parameter/output descriptions) and added new function docs (stdout, filter, lambdaVariables).
• Refreshed ms.date and cross-links throughout the schema reference set.

File summaries

File	Description
docs/reference/schemas/resource/stdout/whatIf.md	Clarifies what-if invocation/output expectations and updates links.
docs/reference/schemas/resource/stdout/test.md	Clarifies test stdout behavior when test.return isn’t defined.
docs/reference/schemas/resource/stdout/set.md	Clarifies set vs what-if stdout expectations and links.
docs/reference/schemas/resource/stdout/delete.md	Documents delete what-if stdout shape and metadata.
docs/reference/schemas/resource/properties/purge.md	Removes TODO and updates metadata date.
docs/reference/schemas/resource/properties/overview.md	Adds _restartRequired canonical property description and link.
docs/reference/schemas/resource/properties/inDesiredState.md	Removes TODO and adds link reference section.
docs/reference/schemas/resource/properties/exist.md	Removes TODO and updates metadata date.
docs/reference/schemas/resource/properties/ensure.md	Clarifies _ensure as legacy-only and links to overview.
docs/reference/schemas/resource/manifest/validate.md	Expands validate semantics + documents richer args argument kinds.
docs/reference/schemas/resource/manifest/test.md	Expands test manifest semantics + args argument kinds + security context.
docs/reference/schemas/resource/manifest/schema/property.md	Clarifies schema vs validate and adds adapter example/links.
docs/reference/schemas/resource/manifest/schema/embedded.md	Fixes _exist reference and minor formatting/link section.
docs/reference/schemas/resource/manifest/resolve.md	Updates kind value wording and expands args argument kinds.
docs/reference/schemas/resource/manifest/adapter.md	Updates adapter examples/terminology (inputKind) and adds guidance.
docs/reference/schemas/overview.md	Expands overview with additional schema links and reorganizes references.
docs/reference/schemas/outputs/resource/test.md	Corrects description and updates execution metadata fields/patterns.
docs/reference/schemas/outputs/resource/set.md	Updates execution metadata fields, required-ness, and type pattern.
docs/reference/schemas/outputs/resource/get.md	Updates execution metadata fields, required-ness, and type pattern.
docs/reference/schemas/outputs/function/list.md	Updates schema references and documents additional function metadata.
docs/reference/schemas/outputs/extension/list.md	Expands extension list output schema properties and capability semantics.
docs/reference/schemas/outputs/config/test.md	Reframes config test output around desired/actual state and exec info.
docs/reference/schemas/outputs/config/set.md	Updates config set output execution metadata and outputs behavior.
docs/reference/schemas/outputs/config/get.md	Updates config get output execution metadata and outputs behavior.
docs/reference/schemas/metadata/Microsoft.DSC/properties.md	Expands metadata semantics and adds restartRequired/copyLoops details.
docs/reference/schemas/extension/stdout/discover.md	Clarifies discover stdout object requirements incl. manifestContent.
docs/reference/schemas/extension/manifest/discover.md	Documents discover manifest property semantics and new extensions arg.
docs/reference/schemas/definitions/resourceType.md	Updates resource type name rules/pattern and adds case-insensitivity note.
docs/reference/schemas/definitions/resourceKind.md	Formatting fixes and corrects example schema/type name slashes.
docs/reference/schemas/definitions/resourceCapabilities.md	Updates capabilities list and adds manifest-to-capability mapping table.
docs/reference/schemas/definitions/parameters/dataTypes.md	Updates secure type casing and notes case sensitivity.
docs/reference/schemas/definitions/message.md	Clarifies message capture semantics and updates type name pattern.
docs/reference/schemas/definitions/functions/builtin/dataTypes.md	Updates function data types metadata and adds linkage to function list.
docs/reference/schemas/config/parameter.md	Updates parameter valid values casing and related text.
docs/reference/schemas/config/metadata.md	Clarifies metadata schema usage and securityContext deprecation note.
docs/reference/schemas/config/functions/uriComponentToString.md	Re-formats syntax/examples and updates CLI usage.
docs/reference/schemas/config/functions/uriComponent.md	Re-formats multiline expression example.
docs/reference/schemas/config/functions/uri.md	Re-formats multiline expression example.
docs/reference/schemas/config/functions/uniqueString.md	Re-formats multiline expression examples.
docs/reference/schemas/config/functions/union.md	Re-formats multiline expression examples.
docs/reference/schemas/config/functions/tryWhich.md	Adds missing header, simplifies boolean logic example, updates output.
docs/reference/schemas/config/functions/tryIndexFromEnd.md	Adds missing header and re-formats examples.
docs/reference/schemas/config/functions/tryGet.md	Adds missing header and re-formats examples.
docs/reference/schemas/config/functions/toUpper.md	Re-formats multiline expression examples.
docs/reference/schemas/config/functions/toLower.md	Re-formats multiline expression examples.
docs/reference/schemas/config/functions/take.md	Adds missing header and re-formats example.
docs/reference/schemas/config/functions/systemRoot.md	Updates anchor link formatting.
docs/reference/schemas/config/functions/sub.md	Minor formatting/line wrapping.
docs/reference/schemas/config/functions/string.md	Re-formats long expressions and updates example filenames/outputs.
docs/reference/schemas/config/functions/stdout.md	Adds new stdout() function reference page.
docs/reference/schemas/config/functions/stateChanged.md	Re-formats multiline expression example.
docs/reference/schemas/config/functions/startsWith.md	Re-formats multiline expression example.
docs/reference/schemas/config/functions/skip.md	Adds missing header.
docs/reference/schemas/config/functions/shallowMerge.md	Adds missing header and normalizes formatting in examples/notes.
docs/reference/schemas/config/functions/resourceId.md	Fixes parameter position metadata and adds explicit output description.
docs/reference/schemas/config/functions/reference.md	Formatting + corrects declared output type list.
docs/reference/schemas/config/functions/range.md	Adds missing header.
docs/reference/schemas/config/functions/path.md	Minor formatting/line wrapping and whitespace cleanup.
docs/reference/schemas/config/functions/parseCidr.md	Re-formats multiline expression example.
docs/reference/schemas/config/functions/parameters.md	Clarifies missing parameter vs missing value behavior + anchor updates.
docs/reference/schemas/config/functions/objectKeys.md	Adds missing header and re-formats examples.
docs/reference/schemas/config/functions/null.md	Minor formatting/line wrapping.
docs/reference/schemas/config/functions/mul.md	Fixes indentation and updates example command text.
docs/reference/schemas/config/functions/lessOrEquals.md	Fixes YAML formatting whitespace.
docs/reference/schemas/config/functions/less.md	Fixes YAML formatting whitespace + line wrapping.
docs/reference/schemas/config/functions/length.md	Re-formats long string default value and updates expected length.
docs/reference/schemas/config/functions/lastIndexOf.md	Adds missing header and re-formats multiline examples.
docs/reference/schemas/config/functions/last.md	Adds missing header.
docs/reference/schemas/config/functions/lambdaVariables.md	Adds new lambdaVariables() function reference page.
docs/reference/schemas/config/functions/json.md	Adds missing header, syntax tweaks, and output typing/note adjustments.
docs/reference/schemas/config/functions/join.md	Tightens type rules for join inputs/delimiter and updates parameter typing.
docs/reference/schemas/config/functions/items.md	Adds missing header.
docs/reference/schemas/config/functions/intersection.md	Adds missing header and re-formats multiline examples.
docs/reference/schemas/config/functions/indexOf.md	Minor example formatting.
docs/reference/schemas/config/functions/if.md	Clarifies type constraints and adds explicit error-conditions section.
docs/reference/schemas/config/functions/greaterOrEquals.md	Fixes YAML formatting whitespace + line wrapping.
docs/reference/schemas/config/functions/greater.md	Fixes YAML formatting whitespace + line wrapping.
docs/reference/schemas/config/functions/filter.md	Adds new filter() function reference page.
docs/reference/schemas/config/functions/equals.md	Fixes syntax signature and updates cross-type comparison semantics.
docs/reference/schemas/config/functions/endsWith.md	Re-formats multiline expression example.
docs/reference/schemas/config/functions/empty.md	Re-formats multiline expression example and output quoting.
docs/reference/schemas/config/functions/div.md	Minor formatting/line wrapping.
docs/reference/schemas/config/functions/dataUriToString.md	Re-formats long base64 data URI string.
docs/reference/schemas/config/functions/dataUri.md	Minor formatting/line wrapping.
docs/reference/schemas/config/functions/createObject.md	Adds missing header and re-formats multiline examples.
docs/reference/schemas/config/functions/copy.md	Adds deprecation note and updates example command/output formatting.
docs/reference/schemas/config/functions/concat.md	Minor formatting/line wrapping.
docs/reference/schemas/config/functions/coalesce.md	Fixes YAML formatting whitespace.
docs/reference/schemas/config/functions/cidrSubnet.md	Re-formats multiline examples and adjusts example output IPs.
docs/reference/schemas/config/functions/cidrHost.md	Re-formats multiline examples and adjusts example output IPs.
docs/reference/schemas/config/functions/bool.md	Minor formatting/line wrapping.
docs/reference/schemas/config/functions/base64ToString.md	Fixes trailing whitespace in example command.
docs/reference/schemas/config/functions/array.md	Updates parameter required-ness metadata.
docs/reference/schemas/config/functions/add.md	Fixes trailing whitespace in example command.
docs/reference/cli/function/list.md	Updates CLI output examples and adds new filtering options documentation.

Review details

Suppressed comments (2)

docs/reference/schemas/outputs/function/list.md:225

• ItemsReference currently points to .../schemas/v3/definitions/functions/builtin/argKind.json, but there is no schemas/v3/definitions/functions/ directory in this repo, so this reference will also 404. If the intent is to reference the function data-type schema, the repo needs to publish it at this path (or the docs should point to the correct existing schema file).
  docs/reference/schemas/config/functions/json.md:230
• After including null in the declared output types, this note is misleading because it says the declared return types don't include null. Consider rephrasing it to just call out that parsing the JSON literal null returns a null value.

> [!NOTE]
> The declared return types for `json()` don't include null. Parsing the JSON literal `null`
> still returns a null value, so `[json('null')]` evaluates to `null`.

• Files reviewed: 109/110 changed files
• Comments generated: 3
• 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)]

Gijs Reijn (@Gijsreyn) - I want to review these changes in more detail, but prefer to review them here for a few reasons:

1. The established model for docs updates is to author/update in this repository and periodically sync to Learn. This ensures that we don't need to leave the repository for technical review and we can sync treat the docs here as a preview for vNext.

   What I haven't done a great job of recently is making sure that we do regularly update the reference docs here as changes land for the next version.

2. This PR is (naturally) very, very large. It's difficult to review all at once, especially in the context of providing feedback (GitHub struggles when you start hitting dozens of comments/suggestions). I would prefer if we could break it up into smaller pieces:

   • ./reference/schemas/definitions and reference/schemas/metadata/Microsoft.DSC
   • ./reference/schemas/config/functions
   • ./reference/schemas/config/*
   • ./reference/schemas/extension
   • ./reference/schemas/resource
   • ./reference/cli, ./reference/schemas/outputs, ./reference/schemas/*

In particular, there's a lot of larger changes to configuration documents that I would like to review separately. There's also the problem of ensuring that newly defined schemas are being placed correctly (and thus that the reference docs are in the correct path, which should always match the relative uri for the schema.

[Gijs Reijn (Gijsreyn)]

Mikey Lombardi (He/Him) (@michaeltlombardi) - copy that. I'm closing this in favor of all the separate doc PRs created.