Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(MAINT) Update OSInfo schema and docs #168

Merged

Commits on Aug 31, 2023

  1. (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
    michaeltlombardi committed Aug 31, 2023
    Configuration menu
    Copy the full SHA
    800172c View commit details
    Browse the repository at this point in the history

Commits on Sep 1, 2023

  1. Configuration menu
    Copy the full SHA
    7d88872 View commit details
    Browse the repository at this point in the history