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