From 5aef8a3fab8781382837b54d5fc0b74f40664213 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 17 Apr 2024 09:50:41 -0500 Subject: [PATCH] (GH-407) Support negative integers in manifest `exitCodes` Prior to this change, the JSON schema for the `exitCodes` property of resource manifests only supported positive integers as exit codes. DSC itself supports negative integers as exit codes, and some apps return negative integers as exit codes for hexadecimal exit codes, like `-2147024891` for `0x80070005`, "Access denied." This change: - Updates both the source and composed schemas to allow negative integers. - Updates the reference documentation to clarify that you must specify integers, that you can't use any alternate formats for those integers, and that the keys in YAML must be wrapped in quotes for parsing. - Addresses #407 by making the schema compliant with the implementation. --- .../reference/schemas/resource/manifest/root.md | 17 ++++++++++++++++- .../2024/04/bundled/outputs/resource/list.json | 4 ++-- .../bundled/outputs/resource/list.vscode.json | 8 ++++---- schemas/2024/04/bundled/resource/manifest.json | 4 ++-- .../04/bundled/resource/manifest.vscode.json | 8 ++++---- schemas/2024/04/resource/manifest.json | 4 ++-- schemas/src/resource/manifest.yaml | 14 +++++++++++--- 7 files changed, 41 insertions(+), 18 deletions(-) diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index fc268094..360a62ef 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -229,11 +229,26 @@ information, see the [DSC Resource manifest provider property schema reference][ The `exitCodes` property defines a set of valid exit codes for the resource and their meaning. Define this property as a set of key-value pairs where: -- The key is a string containing an integer that maps to a known exit code for the resource. +- The key is a string containing an integer that maps to a known exit code for the resource. You + can't use alternate formats for the exit code. For example, instead of the hexadecimal value + `0x80070005` for "Access denied", specify the exit code as `-2147024891`. - The value is a string describing the semantic meaning of that exit code for a human reader. DSC interprets exit code `0` as a successful operation and any other exit code as an error. +> [!TIP] +> If you're authoring your resource manifest in yaml, be sure to wrap the exit code in single +> quotes to ensure the YAML file can be parsed correctly. For example: +> +> ```yaml +> exitCodes: +> '0': Success +> '1': Invalid parameter +> '2': Invalid input +> '3': Registry error +> '4': JSON serialization failed +> ``` + ```yaml Type: object Required: false diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json index d8c2989c..7e9d40b2 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.json +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -219,10 +219,10 @@ "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", "type": "object", "propertyNames": { - "pattern": "^[0-9]+$" + "pattern": "^-?[0-9]+$" }, "patternProperties": { - "^[0-9]+$": { + "^-?[0-9]+$": { "type": "string" } }, diff --git a/schemas/2024/04/bundled/outputs/resource/list.vscode.json b/schemas/2024/04/bundled/outputs/resource/list.vscode.json index 6f1e9249..13476038 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.vscode.json +++ b/schemas/2024/04/bundled/outputs/resource/list.vscode.json @@ -535,11 +535,11 @@ "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", "type": "object", "propertyNames": { - "pattern": "^[0-9]+$", - "patternErrorMessage": "Invalid exit code. Must be a string representing an integer greater than or equal to `0`.\n" + "pattern": "^-?[0-9]+$", + "patternErrorMessage": "Invalid exit code. Must be a string representing a 32-bit signed integer.\n" }, "patternProperties": { - "^[0-9]+$": { + "^-?[0-9]+$": { "type": "string" } }, @@ -557,7 +557,7 @@ "4": "JSON serialization failed" } ], - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\nDefine the keys in this property as strings representing a valid 32-bit signed integer. You\ncan't use alternate formats for the exit code. For example, instead of the hexadecimal value\n`0x80070005` for \"Access denied\", specify the exit code as `-2147024891`. If you're authoring\nyour resource manifest in yaml, be sure to wrap the exit code in single quotes, like\n`'0': Success` instead of `0: Success` to ensure the YAML file can be parsed correctly.\n\nDefine the value for each key as a string explaining what the exit code indicates.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", "defaultSnippets": [ { "label": " Defined exit codes", diff --git a/schemas/2024/04/bundled/resource/manifest.json b/schemas/2024/04/bundled/resource/manifest.json index 8b4999ff..c7c6360f 100644 --- a/schemas/2024/04/bundled/resource/manifest.json +++ b/schemas/2024/04/bundled/resource/manifest.json @@ -80,10 +80,10 @@ "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", "type": "object", "propertyNames": { - "pattern": "^[0-9]+$" + "pattern": "^-?[0-9]+$" }, "patternProperties": { - "^[0-9]+$": { + "^-?[0-9]+$": { "type": "string" } }, diff --git a/schemas/2024/04/bundled/resource/manifest.vscode.json b/schemas/2024/04/bundled/resource/manifest.vscode.json index fbe6c621..a7c9bc84 100644 --- a/schemas/2024/04/bundled/resource/manifest.vscode.json +++ b/schemas/2024/04/bundled/resource/manifest.vscode.json @@ -287,11 +287,11 @@ "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", "type": "object", "propertyNames": { - "pattern": "^[0-9]+$", - "patternErrorMessage": "Invalid exit code. Must be a string representing an integer greater than or equal to `0`.\n" + "pattern": "^-?[0-9]+$", + "patternErrorMessage": "Invalid exit code. Must be a string representing a 32-bit signed integer.\n" }, "patternProperties": { - "^[0-9]+$": { + "^-?[0-9]+$": { "type": "string" } }, @@ -309,7 +309,7 @@ "4": "JSON serialization failed" } ], - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\nDefine the keys in this property as strings representing a valid 32-bit signed integer. You\ncan't use alternate formats for the exit code. For example, instead of the hexadecimal value\n`0x80070005` for \"Access denied\", specify the exit code as `-2147024891`. If you're authoring\nyour resource manifest in yaml, be sure to wrap the exit code in single quotes, like\n`'0': Success` instead of `0: Success` to ensure the YAML file can be parsed correctly.\n\nDefine the value for each key as a string explaining what the exit code indicates.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", "defaultSnippets": [ { "label": " Defined exit codes", diff --git a/schemas/2024/04/resource/manifest.json b/schemas/2024/04/resource/manifest.json index 89957bab..cd75fe21 100644 --- a/schemas/2024/04/resource/manifest.json +++ b/schemas/2024/04/resource/manifest.json @@ -80,10 +80,10 @@ "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", "type": "object", "propertyNames": { - "pattern": "^[0-9]+$" + "pattern": "^-?[0-9]+$" }, "patternProperties": { - "^[0-9]+$": { + "^-?[0-9]+$": { "type": "string" } }, diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 1a902bc3..3b09122d 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -444,11 +444,11 @@ properties: property to indicate human-readable semantic meanings for the DSC Resource's exit codes. type: object propertyNames: - pattern: "^[0-9]+$" + pattern: "^-?[0-9]+$" patternErrorMessage: | - Invalid exit code. Must be a string representing an integer greater than or equal to `0`. + Invalid exit code. Must be a string representing a 32-bit signed integer. patternProperties: - "^[0-9]+$": + "^-?[0-9]+$": type: string unevaluatedProperties: false default: @@ -470,6 +470,14 @@ properties: exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes. + Define the keys in this property as strings representing a valid 32-bit signed integer. You + can't use alternate formats for the exit code. For example, instead of the hexadecimal value + `0x80070005` for "Access denied", specify the exit code as `-2147024891`. If you're authoring + your resource manifest in yaml, be sure to wrap the exit code in single quotes, like + `'0': Success` instead of `0: Success` to ensure the YAML file can be parsed correctly. + + Define the value for each key as a string explaining what the exit code indicates. + [01]: /reference/schemas/resource/manifest/root?#exitcodes defaultSnippets: - label: ' Defined exit codes'