Canonical property schema refs

[ThomasNieto]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest version
• Search the existing issues.

Summary

The current documentation for resource authors is that canonical properties should use the $ref keyword to link out to GitHub for the property reference. However, that won't work if the system is air-gapped.

Excerpt from _exist canonical property.

To add this property to a resource's instance schema, define the property with the following snippet:
"_exist": {
"$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json"
}

To better support air-gapped systems, the documentation should be updated to return the full schema without internet refs and update the canonical property docs with a snippet to include.

Steps to reproduce

n/a

Expected behavior

n/a

Actual behavior

n/a

Error details

n/a

Environment data

n/a

Version

n/a

Visuals

No response

[michaeltlombardi]

This is being worked on as part of #538 - the underlying problem is that DSC doesn't register the canonical property schemas internally, so can't resolve the references.

When DSC does properly register those schemas, authors will be able to define their schemas as documented, even in air-gapped environments.

[ThomasNieto]

Does that also address it for tools calling DSC resources directly without the DSC engine?

[michaeltlombardi]

Tools calling DSC resources directly without the DSC engine would need to pre-load the JSON Schemas for canonical resource properties.

The alternative would be to have every resource re-define these canonical properties in their schema and then every component in the system has to hope that the resources have correctly copied that schema for themselves instead of referencing the canonical schema.

I would recommend that these tools register the schemas for the canonical resource properties in whatever tooling they're using for schema validation. That's functionally how those schema validation tools are able to validate meta schemas - they pre-register the meta schemas (draft 7, draft 2020-12, etc) internally to the library. I think every validator library I've looked at supports registering arbitrary schemas that it can use to resolve references when network access is unavailable or undesired.