PowerShell
Can't define `url` with `embedded` or `command` for manifest schema
Prerequisites
- [X] Write a descriptive title.
- [X] Make sure you are able to repro it on the latest version
- [X] Search the existing issues.
Steps to reproduce
While updating the resource manifest for Microsoft/OSInfo in #168, I had to remove the schema.url property from the manifest for tests to pass - my understanding was that the schema url was strongly suggested for resources that define schema.command, but still usable for schema.embedded.
Double-checking the type definition:
https://github.com/PowerShell/DSC/blob/5a1f8b582edfbe8a040195baa7ff4bdb7231addd/dsc_lib/src/dscresources/resource_manifest.rs#L41-L43
https://github.com/PowerShell/DSC/blob/5a1f8b582edfbe8a040195baa7ff4bdb7231addd/dsc_lib/src/dscresources/resource_manifest.rs#L56-L67
It looks like you have to choose between the three options. You can define the value in the manifest as embedded or command or url, but not embedded and url or command and url, which contradicts prior conversations about using url and command together.
Expected behavior
The following manifest snippets are valid:
{
"schema": {
"embedded": {
// schema definition
}
}
}
```jsonc
{
"schema": {
"command": {
// schema command definition
}
}
}
{
"schema": {
"url": "https://schemas.tailspintoys.com/tstoy.json"
}
}
{
"schema": {
"embedded": {
// schema definition
},
"url": "https://schemas.tailspintoys.com/tstoy.json"
}
}
{
"schema": {
"command": {
// schema command definition
},
"url": "https://schemas.tailspintoys.com/tstoy.json"
}
}
Actual behavior
The following snippets are valid:
{
"schema": {
"embedded": {
// schema definition
}
}
}
{
"schema": {
"command": {
// schema command definition
}
}
}
{
"schema": {
"url": "https://schemas.tailspintoys.com/tstoy.json"
}
}
The following snippets are invalid:
{
"schema": {
"embedded": {
// schema definition
},
"url": "https://schemas.tailspintoys.com/tstoy.json"
}
}
{
"schema": {
"command": {
// schema command definition
},
"url": "https://schemas.tailspintoys.com/tstoy.json"
}
}
Error details
No response
Environment data
Name Value
---- -----
PSVersion 7.3.6
PSEdition Core
GitCommitId 7.3.6
OS Microsoft Windows 10.0.22621
Platform Win32NT
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1
WSManStackVersion 3.0
Version
Latest build from main
Visuals
No response
Consider moving url out to a higher level that is required as that was intended to be used by configuration authoring tools where the user probably has internet access while command and embedded are for deployment scenarios where internet is not always available.
I think we can get away with requiring the resource instance schema defined in schema.embeddded or returned by schema.command to define the $id keyword pointing to the canonical URI for the schema.
For example:
https://github.com/PowerShell/DSC/blob/5a1f8b582edfbe8a040195baa7ff4bdb7231addd/schemas/2023/08/config/document.json#L2-L3
This reuses the semantics of JSON Schema instead of defining a new extra set of information.
Alternatively, if we are adding it as an annotation to the manifest, we could use a key like instanceSchemaID (or whatever) at the top-level of the manifest[^1].
[^1]: Worth noting, I think we should always recommend people to author their manifests with the schema embedded - this makes integration and usage much easier overall and makes it so folks don't need to publish their schemas separately. So in that model, schema.command is supported for development purposes, but schema.embedded is preferred. If you want to reference an external schema from embedded, you can do something like:
```jsonc
{
// rest of the manifest
"schema": {
"embedded": {
"$ref": "https://schemas.tailspin.com/dsc/tstoy.json"
}
}
}
```