Merge pull request #1623 from Gijsreyn/gh-1603/main/update-osinfo-docs

docs: add examples for validating minimum operating system version with `Microsoft/OSInfo`

Author: michaeltlombardi

docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.config.dsc.yaml

@@ -0,0 +1,18 @@
+# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Operating System Assertion
+    type: Microsoft.DSC/Assertion
+    properties:
+      $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+      resources:
+        - name: Minimum operating system version
+          type: Microsoft/OSInfo
+          properties:
+            version: '>= 10.0'
+  - name: Show operating system
+    type: Microsoft.DSC.Debug/Echo
+    properties:
+      output: 'The operating system meets the minimum version requirement.'
+    dependsOn:
+      - "[resourceId('Microsoft.DSC/Assertion', 'Operating System Assertion')]"

docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.md

@@ -0,0 +1,81 @@
+---
+description: Validate a minimum operating system version with Microsoft/OSInfo
+ms.date:     07/11/2026
+ms.topic:    reference
+title:       Validate a minimum operating system version
+---
+
+# Validate a minimum operating system version
+
+This example uses the `Microsoft/OSInfo` resource with the `Microsoft.DSC/Assertion` group
+resource to verify that the operating system version meets a minimum requirement before DSC runs
+another resource.
+
+> [!IMPORTANT]
+> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with
+> DSC. Don't use it in production.
+
+## Definition
+
+The **Operating System Assertion** group contains a `Microsoft/OSInfo` resource instance with the
+version constraint `>= 10.0`. The `Microsoft.DSC/Assertion` resource always invokes **Test** for
+nested instances. If the operating system is earlier than version `10.0`, the configuration fails
+and DSC doesn't invoke **Show operating system**.
+
+:::code language="yaml" source="validate-minimum-version.config.dsc.yaml":::
+
+## Running the configuration
+
+Run the configuration with the [dsc config set][01] command:
+
+```bash
+dsc config set --file ./validate-minimum-version.config.dsc.yaml
+```
+
+On an operating system whose version is at least `10.0`, DSC returns successful results for both
+the assertion group and the dependent echo resource:
+
+```yaml
+results:
+- name: Operating System Assertion
+  type: Microsoft.DSC/Assertion
+  result:
+    beforeState:
+    - name: Minimum operating system version
+      type: Microsoft/OSInfo
+      result:
+        actualState:
+          family: Windows
+          version: 10.0.26200
+          _inDesiredState: true
+    afterState:
+    - name: Minimum operating system version
+      type: Microsoft/OSInfo
+      result:
+        desiredState:
+          version: '>= 10.0'
+        actualState:
+          family: Windows
+          version: 10.0.26200
+          edition: Windows 11
+          bitness: 64
+          architecture: x86_64
+          _inDesiredState: true
+        inDesiredState: true
+        differingProperties:
+        - version
+    changedProperties: []
+- name: Show operating system
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    beforeState:
+      output: The operating system meets the minimum version requirement.
+    afterState:
+      output: The operating system meets the minimum version requirement.
+    changedProperties: null
+messages: []
+hadErrors: false
+```
+
+<!-- Link references -->
+[01]: ../../../../cli/config/set.md

docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md

@@ -2,7 +2,7 @@
 description: >
   Validate operating system information with the Microsoft/OSInfo DSC Resource
   and the dsc resource commands.
-ms.date: 03/25/2025
+ms.date: 07/12/2026
 ms.topic: reference
 title: Validate operating system information with dsc resource
 ---
@@ -32,11 +32,10 @@ dsc resource get -r Microsoft/OSInfo
 
 ```yaml
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
   family: Linux
   version: '20.04'
   codename: focal
-  bitness: '64'
+  bitness: 64
   architecture: x86_64
 ```
 
@@ -49,10 +48,9 @@ dsc resource get -r Microsoft/OSInfo
 
 ```yaml
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
-  family: MacOS
+  family: macOS
   version: 13.5.0
-  bitness: '64'
+  bitness: 64
   architecture: arm64
 ```
 
@@ -64,11 +62,11 @@ dsc resource get --resource Microsoft/OSInfo
 
 ```yaml
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
   family: Windows
   version: 10.0.22621
   edition: Windows 11 Enterprise
-  bitness: '64'
+  bitness: 64
+  architecture: x86_64
 ```
 
 ---
@@ -79,60 +77,60 @@ DSC can use the resource to validate the operating system information. When you
 [dsc resource test][02] command, input JSON representing the desired state of the instance is
 required. The JSON must define at least one instance property to validate.
 
-The resource doesn't implement the [test operation][03]. It relies on the synthetic testing feature
-of DSC instead. The synthetic test uses a case-sensitive equivalency comparison between the actual
-state of the instance properties and the desired state. If any property value isn't an exact match,
-DSC considers the instance to be out of the desired state.
+The resource implements the [test operation][03]. The command passes the desired state to the
+resource over stdin and the resource returns the actual operating system information with an
+`_inDesiredState` value. DSC returns that value as `inDesiredState` in the test result.
+
+All properties except `version` use case-sensitive equality comparison. For `version`, you can use
+an exact version or a constraint with `>`, `<`, `=`, `>=`, or `<=`. For more information, see the
+[version property][04] reference.
 
 # [Linux](#tab/linux)
 
 This test checks whether the `family` property for the instance is `Linux`. It passes the desired
 state for the instance to the command from stdin with the `--file` (`-f`) option.
 
 ```bash
-invalid_instance='{"family": "Linux"}'
-echo $invalid_instance | dsc resource test -r "${resource}" -f -
+valid_instance='{"family": "Linux", "version": ">= 20.04"}'
+echo $valid_instance | dsc resource test -r Microsoft/OSInfo -f -
 ```
 
 ```yaml
 desiredState:
-  family: linux
+  family: Linux
+  version: '>= 20.04'
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
   family: Linux
   version: '20.04'
   codename: focal
-  bitness: '64'
+  bitness: 64
   architecture: x86_64
-inDesiredState: false
-differingProperties:
-- family
+  _inDesiredState: true
+inDesiredState: true
+differingProperties: []
 ```
 
-The result shows that the resource is out of the desired state because the actual state of the
-`family` property wasn't case-sensitively equal to the desired state.
-
-The next test validates that the operating system is a 64-bit Linux operating system. It passes
-the desired state for the instance to the command with the `--input` (`-i`) option.
+The result shows that the resource evaluated both the family and version constraint successfully.
+The next test demonstrates a case-sensitive mismatch.
 
 ```bash
-valid_instance='{ "family": "Linux", "bitness": "64" }'
-echo $valid_instance | dsc resource test -r Microsoft/OSInfo -i $valid_instance
+invalid_instance='{ "family": "linux" }'
+dsc resource test -r Microsoft/OSInfo -i $invalid_instance
 ```
 
 ```yaml
 desiredState:
-  family: Linux
-  bitness: '64'
+  family: linux
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
   family: Linux
   version: '20.04'
   codename: focal
-  bitness: '64'
+  bitness: 64
   architecture: x86_64
-inDesiredState: true
-differingProperties: []
+  _inDesiredState: false
+inDesiredState: false
+differingProperties:
+- family
 ```
 
 # [macOS](#tab/macos)
@@ -141,100 +139,94 @@ This test checks whether the `family` property for the instance is `macOS`. It p
 state for the instance to the command from stdin with the `--file` (`-f`) option.
 
 ```zsh
-invalid_instance='{"family": "macOS"}'
-echo $invalid_instance | dsc resource test -r Microsoft/OSInfo -f -
+valid_instance='{"family": "macOS", "version": ">= 13.0"}'
+echo $valid_instance | dsc resource test -r Microsoft/OSInfo -f -
 ```
 
 ```yaml
 desiredState:
   family: macOS
+  version: '>= 13.0'
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
-  family: MacOS
+  family: macOS
   version: 13.5.0
-  bitness: '64'
+  bitness: 64
   architecture: arm64
-inDesiredState: false
-differingProperties:
-- family
+  _inDesiredState: true
+inDesiredState: true
+differingProperties: []
 ```
 
-The result shows that the resource is out of the desired state because the actual state of the
-`family` property wasn't case-sensitively equal to the desired state.
-
-The next test validates that the operating system is a 64-bit macOS operating system. It passes the
-desired state for the instance to the command with the `--input` (`-i`) option.
+The result shows that the resource evaluates the version constraint in addition to the family.
+The next test demonstrates a case-sensitive mismatch.
 
 ```zsh
-valid_instance='{ "family": "MacOS", "bitness": "64" }'
-dsc resource test -r Microsoft/OSInfo -i $valid_instance
+invalid_instance='{ "family": "MacOS" }'
+dsc resource test -r Microsoft/OSInfo -i $invalid_instance
 ```
 
 ```yaml
 desiredState:
   family: MacOS
-  bitness: '64'
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
-  family: MacOS
+  family: macOS
   version: 13.5.0
-  bitness: '64'
+  bitness: 64
   architecture: arm64
-inDesiredState: true
-differingProperties: []
+  _inDesiredState: false
+inDesiredState: false
+differingProperties:
+- family
 ```
 
 # [Windows](#tab/windows)
 
-This test checks whether the `family` property for the instance is `windows`. It passes the desired
-state for the instance to the command from stdin with the `--file` (`-f`) option.
+This test checks whether the `family` property for the instance is `Windows` and whether the
+operating system version is at least `10.0`. It passes the desired state for the instance to the
+command from stdin with the `--file` (`-f`) option.
 
 ```powershell
-$invalidInstance = @{ family = 'windows' } | ConvertTo-JSON
-$invalidInstance | dsc resource test --resource Microsoft/OSInfo --file -
+$validInstance = @{ family = 'Windows'; version = '>= 10.0' } | ConvertTo-JSON
+$validInstance | dsc resource test --resource Microsoft/OSInfo --file -
 ```
 
 ```yaml
 desiredState:
-  family: windows
+  family: Windows
+  version: '>= 10.0'
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
   family: Windows
   version: 10.0.22621
   edition: Windows 11 Enterprise
-  bitness: "64"
-inDesiredState: false
-differingProperties:
-- family
+  bitness: 64
+  architecture: x86_64
+  _inDesiredState: true
+inDesiredState: true
+differingProperties: []
 ```
 
-The result shows that the resource is out of the desired state because the actual state of the
-`family` property wasn't case-sensitively equal to the desired state.
-
-The next test validates that the operating system is a 64-bit Windows operating system. It passes
-the desired state for the instance to the command with the `--input` (`-i`) option.
+The result shows that the resource evaluated both the family and version constraint successfully.
+The next test demonstrates a case-sensitive mismatch.
 
 ```powershell
-$validInstance = @{
-    family  = 'Windows'
-    bitness = '64'
-} | ConvertTo-JSON
+$invalidInstance = @{ family = 'windows' } | ConvertTo-JSON
 
-dsc resource test --resource Microsoft/OSInfo --input $validInstance
+dsc resource test --resource Microsoft/OSInfo --input $invalidInstance
 ```
 
 ```yaml
 desiredState:
-  family: Windows
-  bitness: '64'
+  family: windows
 actualState:
-  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
   family: Windows
   version: 10.0.22621
   edition: Windows 11 Enterprise
-  bitness: "64"
-inDesiredState: true
-differingProperties: []
+  bitness: 64
+  architecture: x86_64
+  _inDesiredState: false
+inDesiredState: false
+differingProperties:
+- family
 ```
 
 ---
@@ -243,3 +235,4 @@ differingProperties: []
 [01]: ../../../../cli/resource/get.md
 [02]: ../../../../cli/resource/test.md
 [03]: ../../../../../concepts/resources/overview.md#test-operations
+[04]: ../index.md#version