Merge pull request #410 from michaeltlombardi/gh-407/main/update-exit-code-schemas

(GH-407) Support negative integers in manifest `exitCodes`

Author: SteveL-MSFT

docs/reference/schemas/resource/manifest/root.md

@@ -229,11 +229,27 @@ 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 a signed integer that maps to a known exit code for the resource.
+  The exit code must be a literal 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`.
 - 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

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"
             }
           },

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",

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"
         }
       },

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",

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"
         }
       },

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'