(SCHEMA) Replace manifestVersion with $schema

This change updates the schema definitions to replace the `manifestVersion` property for resource manifests with the more canonical `$schema` keyword to reflect the changes from PowerShell#199.
michaeltlombardi · Sep 27, 2023 · f55fec0 · f55fec0
1 parent 9150f03
commit f55fec0
Show file tree

Hide file tree

Showing 5 changed files with 69 additions and 62 deletions.
diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json
@@ -113,18 +113,19 @@
       "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.",
       "type": "object",
       "required": [
-        "manifestVersion",
+        "$schema",
         "type",
         "version",
         "get"
       ],
       "properties": {
-        "manifestVersion": {
-          "title": "Manifest Version",
-          "description": "The semver of the DSC Resource manifest schema to validate this manifest with.",
-          "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
+        "$schema": {
+          "title": "Manifest Schema",
+          "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.",
+          "type": "string",
+          "format": "uri",
           "enum": [
-            "1.0"
+            "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json"
           ]
         },
         "type": {

diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json
@@ -5,18 +5,19 @@
   "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.",
   "type": "object",
   "required": [
-    "manifestVersion",
+    "$schema",
     "type",
     "version",
     "get"
   ],
   "properties": {
-    "manifestVersion": {
-      "title": "Manifest Version",
-      "description": "The semver of the DSC Resource manifest schema to validate this manifest with.",
-      "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
+    "$schema": {
+      "title": "Manifest Schema",
+      "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.",
+      "type": "string",
+      "format": "uri",
       "enum": [
-        "1.0"
+        "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json"
       ]
     },
     "type": {
@@ -92,6 +93,14 @@
     }
   },
   "$defs": {
+    "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json",
+      "title": "DSC Resource fully qualified type name",
+      "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n  - Microsoft.SqlServer/Database\n  - Microsoft.SqlServer.Database/User\n",
+      "type": "string",
+      "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$"
+    },
     "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
@@ -101,14 +110,6 @@
       "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-]+)*))?$",
       "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n  (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n  (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n"
     },
-    "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": {
-      "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json",
-      "title": "DSC Resource fully qualified type name",
-      "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n  - Microsoft.SqlServer/Database\n  - Microsoft.SqlServer.Database/User\n",
-      "type": "string",
-      "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$"
-    },
     "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json",

diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json
@@ -9,7 +9,7 @@
       "label": " Define a resource",
       "markdownDescription": "Defines a standard resource that:\n\n- Can get the current state of an instance\n- Can set an instance to the desired state\n- Relies on DSC's synthetic testing to determine whether an instance is in the desired state\n- Defines an embedded JSON schema.",
       "body": {
-        "manifestVersion": "1.0",
+        "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json",
         "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}",
         "version": "${3:0.1.0}",
         "description": "${4:Synopsis for the resource's purpose}",
@@ -48,7 +48,7 @@
       "label": " Define a resource (group)",
       "markdownDescription": "Defines a group resource that expects a list of resource instances and operates on them.",
       "body": {
-        "manifestVersion": "1.0",
+        "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json",
         "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}",
         "version": "${3:0.1.0}",
         "description": "${4:Synopsis for the resource's purpose}",
@@ -103,7 +103,7 @@
       "label": " Define a resource (provider)",
       "markdownDescription": "Defines a provider resource that enables users to define non-command-based DSC Resources in\nthe configuration.",
       "body": {
-        "manifestVersion": "1.0",
+        "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json",
         "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}",
         "version": "${3:0.1.0}",
         "description": "${4:Synopsis for the resource's purpose}",
@@ -167,7 +167,7 @@
       "label": " Define a resource (assertion-only)",
       "markdownDescription": "Defines an assertion resource that can get the current state of an instance but not configure\nit. By default, the resource relies on DSC's synthetic testing feature. If the resource\nimplements the `test` operation itself, define the `test` property.",
       "body": {
-        "manifestVersion": "1.0",
+        "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json",
         "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}",
         "version": "${3:0.1.0}",
         "description": "${4:Synopsis for the resource's purpose}",
@@ -196,20 +196,21 @@
   ],
   "type": "object",
   "required": [
-    "manifestVersion",
+    "$schema",
     "type",
     "version",
     "get"
   ],
   "properties": {
-    "manifestVersion": {
-      "title": "Manifest Version",
-      "description": "The semver of the DSC Resource manifest schema to validate this manifest with.",
-      "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
+    "$schema": {
+      "title": "Manifest Schema",
+      "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.",
+      "type": "string",
+      "format": "uri",
       "enum": [
-        "1.0"
+        "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json"
       ],
-      "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe semver of the DSC Resource manifest schema to validate this manifest with.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#manifestversion\n",
+      "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be the canonical URL of the Command-based DSC Resource Manifest schema\nthat the manifest is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#schema\n",
       "markdownEnumDescriptions": [
         "_Initial release_\n"
       ]
@@ -311,16 +312,6 @@
             "2023": {
               "08": {
                 "definitions": {
-                  "semver.json": {
-                    "$schema": "https://json-schema.org/draft/2020-12/schema",
-                    "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
-                    "type": "string",
-                    "title": "Semantic Version",
-                    "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n",
-                    "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-]+)*))?$",
-                    "patternErrorMessage": "Invalid value, must be a semantic version like `<major>.<minor>.<patch>`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n",
-                    "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n  (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n  (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n"
-                  },
                   "resourceType.json": {
                     "$schema": "https://json-schema.org/draft/2020-12/schema",
                     "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json",
@@ -331,6 +322,16 @@
                     "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```yaml\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserve-view=true\n",
                     "patternErrorMessage": "Invalid type name. Valid resource type names always define an owner and a name separated by a\nslash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace\nthe resource under the owner, like `Microsoft.Windows/Registry`.\n"
                   },
+                  "semver.json": {
+                    "$schema": "https://json-schema.org/draft/2020-12/schema",
+                    "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
+                    "type": "string",
+                    "title": "Semantic Version",
+                    "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n",
+                    "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-]+)*))?$",
+                    "patternErrorMessage": "Invalid value, must be a semantic version like `<major>.<minor>.<patch>`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n",
+                    "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n  (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n  (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n"
+                  },
                   "commandExecutable.json": {
                     "$schema": "https://json-schema.org/draft/2020-12/schema",
                     "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json",

diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json
@@ -5,18 +5,19 @@
   "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.",
   "type": "object",
   "required": [
-    "manifestVersion",
+    "$schema",
     "type",
     "version",
     "get"
   ],
   "properties": {
-    "manifestVersion": {
-      "title": "Manifest Version",
-      "description": "The semver of the DSC Resource manifest schema to validate this manifest with.",
-      "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json",
+    "$schema": {
+      "title": "Manifest Schema",
+      "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.",
+      "type": "string",
+      "format": "uri",
       "enum": [
-        "1.0"
+        "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json"
       ]
     },
     "type": {

diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml
@@ -30,7 +30,7 @@ defaultSnippets:
       - Relies on DSC's synthetic testing to determine whether an instance is in the desired state
       - Defines an embedded JSON schema.
     body:
-      manifestVersion: '1.0'
+      $schema:          <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
       type:            '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
       version:         '${3:0.1.0}'
       description:     ${4:Synopsis for the resource's purpose}
@@ -57,10 +57,10 @@ defaultSnippets:
     markdownDescription: |-
       Defines a group resource that expects a list of resource instances and operates on them.
     body:
-      manifestVersion: '1.0'
+      $schema:          <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
       type:            '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
       version:         '${3:0.1.0}'
-      description:     ${4:Synopsis for the resource's purpose}
+      description:      ${4:Synopsis for the resource's purpose}
       get:
         executable: ${5:executable name}
         args:       ['${6:argument}']
@@ -96,10 +96,10 @@ defaultSnippets:
       Defines a provider resource that enables users to define non-command-based DSC Resources in
       the configuration.
     body:
-      manifestVersion: '1.0'
+      $schema:          <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
       type:            '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
       version:         '${3:0.1.0}'
-      description:     ${4:Synopsis for the resource's purpose}
+      description:      ${4:Synopsis for the resource's purpose}
       get:
         executable: ${5:executable name}
         args:       ['${6:argument}']
@@ -141,10 +141,10 @@ defaultSnippets:
       it. By default, the resource relies on DSC's synthetic testing feature. If the resource
       implements the `test` operation itself, define the `test` property.
     body:
-      manifestVersion: '1.0'
+      $schema:          <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
       type:            '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
       version:         '${3:0.1.0}'
-      description:     ${4:Synopsis for the resource's purpose}
+      description:      ${4:Synopsis for the resource's purpose}
       get:
         executable: ${5:executable name}
         args:       ['${6:argument}']
@@ -161,27 +161,30 @@ defaultSnippets:
 
 type: object
 required:
-  - manifestVersion
+  - $schema
   - type
   - version
   - get
 properties:
-  manifestVersion:
-    title: Manifest Version
+  $schema:
+    title: Manifest Schema
     description: >-
-      The semver of the DSC Resource manifest schema to validate this manifest with.
-    $ref: /<PREFIX>/<VERSION>/definitions/semver.yaml
+      This property must be the canonical URL of the Command-based DSC Resource Manifest schema
+      that the manifest is implemented for.
+    type:   string
+    format: uri
     enum:
-      - '1.0'
+      - <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
     # VS Code Only
     markdownDescription: |
       ***
       [_Online Documentation_][01]
       ***
 
-      The semver of the DSC Resource manifest schema to validate this manifest with.
+      This property must be the canonical URL of the Command-based DSC Resource Manifest schema
+      that the manifest is implemented for.
 
-      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/root?<DOCS_VERSION_PIN>#manifestversion
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/root?<DOCS_VERSION_PIN>#schema
     markdownEnumDescriptions:
       - | # 1.0
           _Initial release_