From 36ca4610c60d917ff36cf5b90887f9b733338767 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Fri, 4 Sep 2026 04:44:07 +0200 Subject: [PATCH] docs: Update extension schema reference --- .../schemas/extension/manifest/discover.md | 98 +++++--- .../schemas/extension/manifest/root.md | 236 ++++++++++++++++-- .../schemas/extension/stdout/discover.md | 64 +++-- 3 files changed, 325 insertions(+), 73 deletions(-) diff --git a/docs/reference/schemas/extension/manifest/discover.md b/docs/reference/schemas/extension/manifest/discover.md index 44b70c8ae..d1e0bef01 100644 --- a/docs/reference/schemas/extension/manifest/discover.md +++ b/docs/reference/schemas/extension/manifest/discover.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'discover' property in a DSC extension manifest -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC extension manifest discover property schema reference --- @@ -21,16 +21,39 @@ Type: object ## Description -A DSC extension that can enumerate DSC resource not discoverable in the `PATH` or `DSC_RESOURCE_PATH` environment variables -should define the `export` property in its manifest. This property defines how DSC can get the -path to otherwise undiscoverable manifests. +A DSC extension that can enumerate DSC resources not discoverable in the `PATH` or +`DSC_RESOURCE_PATH` environment variables should define the `discover` property in its manifest. +This property defines how DSC can get the path to, or the content of, otherwise undiscoverable +manifests. When the manifest defines this property, the extension has the `discover` capability. -When the DSC performs discovery for any operation, it calls the command defined by this property. -The extension must return the path to discovered manifests as [JSON lines][05]. Each JSON Line -should be an object representing the instance and validate against the -[DSC extension discover operation stdout schema reference][06]. +When DSC performs discovery for any operation, it calls the command defined by this property with +the folder containing the extension manifest as the working directory. The extension must return +the discovered manifests as [JSON Lines][01]. Each JSON Line must be an object that validates +against the [DSC extension discover operation stdout schema reference][02]. -## Required Properties +## Examples + +The following example shows the `discover` property from the manifest for the +`Microsoft.PowerShell/Discover` extension. It runs a PowerShell script and passes the list of +manifest file extensions that DSC recognizes to the script's `-extensions` parameter as a quoted +string. + +```yaml +discover: + executable: pwsh + args: + - -NoLogo + - -NonInteractive + - -ExecutionPolicy + - Bypass + - -NoProfile + - -Command + - ./powershell.discover.ps1 + - extensionsArg: -extensions + includeQuotes: true +``` + +## Required properties The `discover` definition must include these properties: @@ -52,18 +75,15 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -extension input to an argument, you can define a single item in the array as a -[JSON object](#json-input-argument), indicating the name of the argument with the `jsonInputArg` -string property and whether the argument is mandatory for the command with the `mandatory` boolean -property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +can be a string representing a static argument or an +[extensions argument](#extensions-argument) object that receives the list of file extensions DSC +recognizes for manifests. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +ItemsType: [string, object(Extensions argument)] ``` #### String arguments @@ -75,23 +95,37 @@ command, like `discover` or `--format`. Type: string ``` -#### JSON input argument +#### Extensions argument + +Defines an argument that receives the list of file extensions DSC recognizes for manifests. Use +this argument so the extension can find manifests by file name without hard-coding the naming +conventions. This argument type was added in DSC version 3.3.0. + +DSC passes the value of `extensionsArg` to the command, followed by a single argument containing +the comma-separated list of recognized file extensions: + +- `.dsc.adaptedresource.json`, `.dsc.adaptedresource.yaml`, and `.dsc.adaptedresource.yml` +- `.dsc.extension.json`, `.dsc.extension.yaml`, and `.dsc.extension.yml` +- `.dsc.manifests.json`, `.dsc.manifests.yaml`, and `.dsc.manifests.yml` +- `.dsc.resource.json`, `.dsc.resource.yaml`, and `.dsc.resource.yml` -Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object -with the following properties: +An extensions argument is defined as a JSON object with the following properties: -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, - even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. +- `extensionsArg` (required) - The argument to pass before the list of file extensions, like + `--extensions`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the list of file extensions in + double quotes. The default is `false`. -You can only define one JSON input argument per arguments array. +> [!NOTE] +> In DSC 3.2.x, the `args` array for the `discover` property accepted the same JSON input argument +> object (`jsonInputArg`) as the `get.args` property in resource manifests. Starting with DSC +> 3.3.0, that form isn't valid for the `discover` property. ```yaml -Type: object -RequiredProperties: [jsonInputArg] +Type: object +RequiredProperties: [extensionsArg] ``` -[05]: https://jsonlines.org/ -[06]: ../stdout/discover.md + +[01]: https://jsonlines.org/ +[02]: ../stdout/discover.md diff --git a/docs/reference/schemas/extension/manifest/root.md b/docs/reference/schemas/extension/manifest/root.md index 8fa803f28..1b9f3a932 100644 --- a/docs/reference/schemas/extension/manifest/root.md +++ b/docs/reference/schemas/extension/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC extension manifest -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: Command-based DSC extension manifest schema reference --- @@ -21,14 +21,20 @@ Type: object ## Description -Every command-based DSC Resource must have a manifest. The manifest file must: +Every command-based DSC extension must have a manifest. The manifest file must: 1. Be discoverable in the `PATH` environment variable. 1. Be formatted as either JSON or YAML. -1. Follow the naming convention `.dsc.resource.`. Valid extensions include `json`, - `yml`, and `yaml`. +1. Follow the naming convention `.dsc.extension.`. Valid extensions include + `json`, `yml`, and `yaml`. 1. Be valid for the schema described in this document. +DSC infers the capabilities of an extension from the operation properties defined in the manifest. +An extension has the `discover` capability when the manifest defines the [discover](#discover) +property, the `import` capability when the manifest defines the [import](#import) property, and +the `secret` capability when the manifest defines the [secret](#secret) property. An extension +that doesn't define any of these properties has no capabilities. + The rest of this document describes the manifest's schema. ## Required properties @@ -38,7 +44,6 @@ The manifest must include these properties: - [$schema](#schema) - [type](#type) - [version](#version) -- [get](#get) ## Properties @@ -52,8 +57,9 @@ The JSON schemas for DSC are published in multiple versions and forms. This docu the latest version of the schema. As a convenience, you can specify either the full URI for the schema hosted in GitHub or use the shorter `aka.ms` URI. You can specify the schema for a specific semantic version, the latest schema for a minor version, or the latest schema for a major version -of DSC. For more information about schema URIs and versioning, see -[DSC JSON Schema URIs](../../schema-uris.md). +of DSC. DSC recognizes the URIs for every version folder listed below, but the schemas aren't +published to every recognized folder. For more information about schema URIs and versioning, see +[DSC JSON Schema URIs][01]. For every version of the schema, there are three valid URLs: @@ -77,8 +83,8 @@ For every version of the schema, there are three valid URLs: it includes additional definitions that provide contextual help and snippets that the others don't include. - This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still - validate the document when it uses this schema, other tools may error or behave in unexpected + This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still + validate the document when it uses this schema, other tools may error or behave in unexpected ways. ```yaml @@ -89,33 +95,107 @@ ValidValues: [ https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/extension/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/extension/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/extension/manifest.vscode.json https://aka.ms/dsc/schemas/v3/extension/manifest.json https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.3/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.1/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.0/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/extension/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1/extension/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/extension/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.3/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.1/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/extension/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1.0/extension/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/extension/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0.1/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.1/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.1/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0.0/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.0/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.0/bundled/extension/manifest.vscode.json ] ``` ### type -The `type` property represents the fully qualified type name of the extension. For more information -about extension type names, see [DSC extension fully qualified type name schema reference][01]. +The `type` property represents the fully qualified type name of the extension. Extension type +names use the same syntax as resource type names: an owner segment, any number of namespace +segments, a forward slash (`/`), and a name segment. For more information about type names, see +[DSC Resource fully qualified type name schema reference][02]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,3}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### version @@ -126,7 +206,36 @@ The `version` property must be the current version of the extension as a valid s ```yaml Type: string Required: true -Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +Pattern: ^(?(?:0|[1-9]\d*))\.(?(?:0|[1-9]\d*))\.(?(?:0|[1-9]\d*))(?:-(?(?:(?:0|[1-9]\d*)|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:(?:0|[1-9]\d*)|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +### condition + +The `condition` property defines a DSC configuration expression that DSC evaluates during +discovery to determine whether the extension is usable on the system. If the expression evaluates +to `false`, DSC discards the extension during discovery and writes a debug message indicating that +the manifest's condition wasn't met. If the manifest doesn't define this property, or the +expression evaluates to `true`, DSC discovers the extension as normal. + +Use this property for extensions with external prerequisites. For example, the +`Microsoft.PowerShell/Discover` extension defines the condition +`[not(equals(tryWhich('pwsh'), null()))]` so that DSC ignores the extension when `pwsh` isn't +available on the system. + +```yaml +Type: string +Required: false +``` + +### deprecationMessage + +The `deprecationMessage` property indicates that the extension is deprecated. When this property +is defined, DSC raises a warning that includes the message whenever it invokes the extension. DSC +also reports the message in the output of the `dsc extension list` command. + +```yaml +Type: string +Required: false ``` ### description @@ -157,16 +266,86 @@ ItemsPattern: ^\w+$ The `discover` property defines how to call the extension to discover DSC resources that aren't available in the `PATH` or `DSC_RESOURCE_PATH` environment variables. When this property is -defined, DSC invokes the `discover` operation for the extension during the resource discovery phase -of any `dsc config` or `dsc resource` command. +defined, the extension has the `discover` capability and DSC invokes the `discover` operation for +the extension during the resource discovery phase of any `dsc config` or `dsc resource` command. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` property is optional. For more -information, see [DSC extension manifest discover property schema reference][02]. +of the command to call, is mandatory. The `args` property is optional. For more information, see +[DSC extension manifest discover property schema reference][03]. ```yaml Type: object -Required: true +Required: false +``` + +### import + +The `import` property defines how to call the extension to convert a file that DSC can't parse +directly into a configuration document. When this property is defined, the extension has the +`import` capability. + +When you pass a file to a `dsc config` command with the `--file` option, DSC checks whether any +extension with the `import` capability handles the file's extension. DSC uses the content returned +by the first extension that successfully imports the file as the configuration document. If no +extension imports the file, DSC reads the file directly. + +The value of this property must be an object with the following properties: + +- `fileExtensions` (required) - An array of strings defining the file extensions the extension can + import, like `["bicep"]`. Define the extensions without the leading period. If this array is + empty, DSC writes a warning during discovery and the extension can't import any files. +- `executable` (required) - The name of the command to run. The value must be the name of a + command discoverable in the system's `PATH` environment variable or the full path to the command. +- `args` (optional) - The list of arguments to pass to the command. Each item in the array can be + a string representing a static argument, like `--format`, or an object with the `fileArg` + property. For the `fileArg` item, DSC passes the value of `fileArg` followed by the absolute path + to the file to import. If `fileArg` is an empty string, DSC passes only the path. +- `output` (optional) - A DSC configuration expression that DSC evaluates after the command + completes to transform the command's output into the configuration document. Use the `stdout()` + function in the expression to access the text the command wrote to stdout. When this property + isn't defined, DSC uses the command's output as the configuration document without modification. + +```yaml +Type: object +Required: false +``` + +### importParameters + +The `importParameters` property has the same structure as the [import](#import) property. DSC +reserves this property for a future operation that imports parameters from files in formats DSC +can't parse directly. DSC validates this property when it loads the manifest but doesn't currently +invoke the command it defines. + +```yaml +Type: object +Required: false +``` + +### secret + +The `secret` property defines how to call the extension to retrieve a secret from a vault at +runtime. When this property is defined, the extension has the `secret` capability and DSC can +invoke the extension for the [secret()][04] configuration function. + +The value of this property must be an object with the following properties: + +- `executable` (required) - The name of the command to run. The value must be the name of a + command discoverable in the system's `PATH` environment variable or the full path to the command. +- `args` (optional) - The list of arguments to pass to the command. Each item in the array can be + a string representing a static argument, an object with the `nameArg` property, or an object + with the `vaultArg` property. For the `nameArg` item, DSC passes the value of `nameArg` followed + by the name of the secret to retrieve. For the `vaultArg` item, DSC passes the value of + `vaultArg` followed by the name of the vault when the `secret()` function specifies a vault. When + the function doesn't specify a vault, DSC omits the `vaultArg` item entirely. + +The command must write the secret value to stdout as a single line. If the command writes more +than one line to stdout, DSC raises an error. If the command writes nothing to stdout, DSC treats +the secret as not found for that extension. + +```yaml +Type: object +Required: false ``` ### exitCodes @@ -198,9 +377,24 @@ DSC interprets exit code `0` as a successful operation and any other exit code a ```yaml Type: object Required: false -PropertyNamePattern: ^-?[0-9]+# +PropertyNamePattern: ^-?[0-9]+$ PropertyValueType: string ``` -[01]: ../../definitions/extensionType.md -[02]: discover.md +### metadata + +The `metadata` property defines an object of arbitrary additional data for the extension. DSC +doesn't validate or use the values in this object. Use this property to include any information +about the extension that isn't covered by the other manifest properties, like details for +integrating tools. + +```yaml +Type: object +Required: false +``` + + +[01]: ../../schema-uris.md +[02]: ../../definitions/resourceType.md +[03]: discover.md +[04]: ../../config/functions/secret.md diff --git a/docs/reference/schemas/extension/stdout/discover.md b/docs/reference/schemas/extension/stdout/discover.md index 7afbf4afd..eb9e3db6e 100644 --- a/docs/reference/schemas/extension/stdout/discover.md +++ b/docs/reference/schemas/extension/stdout/discover.md @@ -1,6 +1,6 @@ --- -description: JSON schema reference for the 'discover' property in a DSC extension manifest -ms.date: 02/28/2025 +description: JSON schema reference for the 'discover' operation output in a DSC extension +ms.date: 09/01/2026 ms.topic: reference title: DSC extension discover operation stdout schema reference --- @@ -9,8 +9,7 @@ title: DSC extension discover operation stdout schema reference ## Synopsis -Represents the path to a manifest not discoverable in the `PATH` or `DSC_RESOURCE_PATH` environment -variables. +Represents a manifest not discoverable in the `PATH` or `DSC_RESOURCE_PATH` environment variables. ## Metadata @@ -22,37 +21,58 @@ Type: object ## Description -Represents the actual state of a resource instance in DSC path to a discovered DSC resource or -extension manifest on the system. DSC expects every JSON Line emitted to stdout for the -**Discover** operation to adhere to this schema. +Represents a DSC manifest that the extension discovered, either as the absolute path to the +manifest file on the system or as the content of the manifest. DSC expects every JSON Line emitted +to stdout for the **Discover** operation to adhere to this schema. -The output must be a JSON object. The object must define the full path to the discovered manifest. -If an extension returns JSON that is invalid against this schema, DSC raises an error. +The output must be a JSON object. The object must define exactly one of the [manifestPath][01] or +[manifestContent][02] properties. If an extension returns JSON that is invalid against this schema, +DSC raises an error. -If the extension doesn't discover any manifests, it must return nothing to stdout and exit with -code `0`. An empty output with a zero exit code indicates no resources were found. A non-zero exit -code indicates an error, even if stdout is empty. +Each discovered manifest must be emitted as a separate JSON Line to stdout. If the extension +doesn't discover any manifests, it must return nothing to stdout and exit with code `0`. An empty +output with a zero exit code indicates no resources were found. A non-zero exit code indicates an +error, even if stdout is empty. -## Required Properties +DSC uses the discovered manifests to find resources, including adapted resources and resources +defined in manifest lists. Extensions can't currently discover other extensions. If a discovered +manifest defines an extension, DSC ignores it. -The output for the `discover` operation must include these properties: +## Required properties + +The output for the `discover` operation must include exactly one of these properties: - [manifestPath](#manifestpath) +- [manifestContent](#manifestcontent) ## Properties ### manifestPath -The value for this property must be the absolute path to a manifest file on the system. The -manifest can be for a DSC resource or extension. If the returned path doesn't exist, DSC raises an -error. +The value for this property must be the absolute path to a manifest file on the system. DSC +determines how to load the manifest from the file name, so the file name must follow one of the +manifest naming conventions, like `.dsc.resource.json`, `.dsc.adaptedresource.json`, +or `.dsc.manifests.json`. -Each discovered manifest must be emitted as a separate JSON Line to stdout. If no manifests are -discovered, the extension must not emit any output to stdout. +If the returned path isn't absolute, DSC raises an error. If DSC can't load the manifest at the +returned path, it writes an informational message and skips that manifest. ```yaml Type: string -Required: true +Required: true (when manifestContent isn't defined) +``` + +### manifestContent + +The value for this property must be the content of a manifest as a JSON object. DSC processes the +value the same way it processes the content of a manifest file, including evaluating the +`condition` property of the manifest. The value can be a resource manifest, an adapted resource +manifest, or a manifest list. If the value isn't a valid manifest, DSC raises an error. This +property was added in DSC version 3.3.0. + +```yaml +Type: object +Required: true (when manifestPath isn't defined) ``` ## Exit codes @@ -62,3 +82,7 @@ The extension must return one of the following exit codes: - `0` - Success. The extension completed discovery. If no manifests were found, stdout is empty. - Non-zero - Error. DSC treats any non-zero exit code as a failure and surfaces the extension's stderr output as an error message. + + +[01]: #manifestpath +[02]: #manifestcontent