(PowerShellGH-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 PowerShell#407 by making the schema compliant with the implementation.
michaeltlombardi · Apr 29, 2024 · 5aef8a3 · 5aef8a3
1 parent 0157276
commit 5aef8a3
Show file tree

Hide file tree

Showing 7 changed files with 41 additions and 18 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/root?<DOCS_VERSION_PIN>#exitcodes
     defaultSnippets:
       - label:     ' Defined exit codes'