Proposed additional canonical properties

[mgreenegit]

Summary of the new feature / enhancement

Suggesting the following for discussion and consideration. This is based on a review of 2500 resources currently available in the PowerShell Gallery. The motivation to include items from this list (some or all) is to standardize across resources so that users have a consistent experience across resources from many authors. Of course, anyone can choose to drop the underscore and re-implement for any reason.

See technical details section for suggested list.

Additional considerations for discussion that feel a bit more like they would have specific implementation requirements so might not be suitable? "Server" "Database" "State"

Finally, it might be worth discussing if it would be possible to standardize a password parameter to lead authors towards best practices for security. Referencing a secure password service rather than storing the string in a file, for example. "Password"

Proposed technical implementation details

_name

title: Name
description: >-
  Indicates a short string that provides a name for the instance.
type: string

_description

title: Description
description: >-
  Indicates a long string that provides details about the instance.
type: string

_version

title: Version
description: >-
  Indicates a version number for the instance. Semantic version format is preferred but not required.
type: string

_path

title: File System Path
description: >-
  Indicates the path to a file or folder represented in DOS, UNC, or Files System Hierarchy format. Should not be used for Internet locations.
type: string

_url

title: Uniform Resource Locator
description: >-
  Indicates a reference to a specific Internet resource using format protocol://nameorip:port/path. Offen used when referencing untrusted content. A URI path is also acceptable.
type: string

[michaeltlombardi]

Edit:

My main concern about these common properties is that their documentation will usually need to be very specific to the resource they're used on - what the property is actually used for, how it must be validated, etc - rather than the existing canonical properties, which describe how the resource itself behaves.

I'm not sure about the _name and _description properties - but if we were to specify them, I would suggest something like:

_name

title:       Name
description: Indicates a short string that provides a name for the instance.
type:        string
minLength:   1
maxLength:   50              # could be lower
pattern:     ^(\w|\s|-|\.)+$ # Could be more or less strict

_description

title:       Description
description: Indicates a long string that provides details about the instance.
type:        string
minLength:   1

_version

This one is interesting, because I think it's more helpful to have a few different version options than just an arbitrary string. We already have the semver schema people can reference.

_path

This one would be most helpful if we had a way to make it easier for people to assemble the supported paths from a few different definitions. A pseudo example of this all-in-one would be:

title: File System Path
description: >-
  Indicates the path to a file or folder represented in DOS, UNC, or Files System Hierarchy format. 
  Should not be used for Internet locations.
type: string
anyOf:
 - $ref: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/paths/dos.json
 - $ref: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/paths/unc.json
 - $ref: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/paths/posix.json

_url

This one may or may not be as useful, because people can do this:

url:
  title: Update Endpoint URL
  description: >-
    Defines the endpoint URL for the update service. When this value isn't defined,
    TSToy won't search for updates.
  type:   string
  format: uri