Meta Issue: Define extended JSON schema vocabulary for DSC itself and for DSC resource instance schemas

[michaeltlombardi]

Summary of the new feature / enhancement

As a contributor to DSC, an integrating developer, and a DSC Resource author, I want to be able to use consistent non-standard keywords to simplify and clarify the schemas I author and consume for DSC.

For example, we currently have a few concepts that aren't represented in the standard vocabularies for JSON Schema.

• Our numeric types use the format keyword with non-standard formats like uint8 - useful for consumers and integrating developers, but only an annotation for most consuming libraries.

• We have the concept of key properties, but no equivalent in JSON Schema. We have two proposals for managing this - defining a canonical _keys property, or defining a keyword like x-keyProperty (for per-property annotation) or x-keyProperties (for per-resource annotation).

• We currently require resource authors to define their canonical properties in their manifests with the $ref keyword, like:

  "_exist": {
    "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json"
  }

  However, it would be useful for authors to be able to indicate this with a keyword like x-ensurable or x-canonicalProperties:

  title: My resource
  type: object
  x-ensurable: true
  properties:
    path: { type: string }

  title: My resource
  type: object
  x-canonicalProperties: [_exist]
  properties:
    path: { type: string }

• We could provide a way to indicate whether a schema is case insensitive with x-caseInsensitive:

  title: My resource
  type: object
  x-caseInsensitive: false # default
  properties:
    path: { type: string }
    options:
      type: array
      items:
        type: string
        enum: [foo, bar, baz]

  title: My resource
  type: object
  x-caseInsensitive: true # all property names and values
  properties:
    path: { type: string }
    options:
      type: array
      items:
        type: string
        enum: [foo, bar, baz]

  title: My resource
  type: object
  properties:
    path: { type: string }
    options:
      type: array
      items:
        type: string
        enum: [foo, bar, baz]
        x-caseInsensitive: true # Just these values

• We could define annotation keywords for documentation purposes beyond title/description in the standard vocabulary and the (undocumented) *markdownDescription keywords that VS Code recognizes.

• We could define annotation keywords that indicate other useful information not defineable in the standard vocabulary, like x-availability to indicate when a property was added or deprecated with a short message - you can use deprecated: true to indicate that a property is now deprecated, but not why, which usually means adding a message to the description and hoping it gets read.

• We could support custom formats like filePath or glob, clarifying expectations (and potentially providing validation)

We will probably find other useful cases for an extended vocabulary, and can progressively enhance the DevX for resource authors as we do - addressing per-language concerns in that language's resource development kit implementation, but certainly there's value in the annotation keywords (which don't change how a schema is validated or expanded).

Proposed technical implementation details (optional)

I think the most coherent option is to create a separate crate, like dsc_jsonschema, which is concerned primarily¹ with defining any custom keywords, validation options, etc that we can then consume in dsc_lib and the eventual rust RDK.

This would also make the vocabulary and any other conveniences available more broadly, especially if published to a public repository.

While I proposed a few use cases above, I believe that any cases we decide to tackle should be extracted into sub-issues where the design discussion can be more appropriately contained.

Footnotes

1. Out of scope in this issue, this would also give us a place to coherently place custom transforms / etc for schemars generating schemas to simplify/improve how schemas generate, like creating an enum subschema instead of a oneOf subschema for string enumerations with documentation. ↩