Merge pull request #168 from michaeltlombardi/maint/main/update-osinf…

…o-docs

(MAINT) Update OSInfo schema and docs

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

osinfo/osinfo.dsc.resource.json

@@ -15,58 +15,66 @@
     "schema": {
         "embedded": {
             "$schema": "http://json-schema.org/draft-07/schema#",
+            "$id": "https://raw.githubusercontent.com/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"
                 }
             }
         }

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,

schemas/resources/Microsoft/OSInfo/v0.1.0/schema.json

@@ -0,0 +1,65 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://raw.githubusercontent.com/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"
+        }
+    }
+}

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://raw.githubusercontent.com/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