(DOCS) Define decomposed schemas #94
Conversation
This change defines a set of JSON Schema documents for DSC. Instead of a few monolithic schema documents, this change defines the schemas as smaller, more manageable documents that can be bundled as needed. These schemas are hand-authored and more specific than the schemas generated with the `dsc schema` command. The schemas included here are implemented with loose validation, but we can support strict validation side-by-side. The schemas are organized into subfolders: - In the `bundled` folder, the schema documents include a synthetic example of the bundling process. For this change, they were generated by hand, but they could be composed with tooling instead. - In the `config` folder, the schema documents validate a DSC Configuration document. - In the `definitions` folder, the schema documents represent reused definitions for validation and/or documentation. The `title` and `description` keywords for instances in a JSON Schema are used by authoring tools to provide contextual documentation. - In the `outputs` folder, the schema documents represent the output users and integrating tools should expect from calling `dsc`. Tools may use these definitions to generate their own structs in their application code to more readily and accurately handle output from DSC. - In the `resource` folder, the `manifest*` schema documents validate a command-based DSC Resource manifest. - In the `resource/properties` folder, the schema documents represent standard DSC Resource properties that have well-defined usage. The schema URL and the ID names for the schemas is best-effort but should not be treated as canonical without further discussion. The documents include comments indicating ambiguities or questions that they raise.
This change extends the JSON Schema definition for DSC Resource manifests that embed their schema. It: - makes the `$schema`, `type`, and `properties` keys mandatory - limits the `$schema` to known schemas and `type` to `object` - Requires at least one property defined on the object - Adds the standard properties to the list of available properties, so authors get intellisense for them.
This change moves the parameter-block related JSON schemas together for clarity and shifts from in-document definitions to references. This was required for solving an issue with how VS Code resolves references without adding even more complex handling.
This change adds a new build script to the schema folder. By default, it generated bundled schema files for the configuration document and resource manifest schemas. It can bundle schemas in four formats: - JSON - YAML - JSON (VS Code) - YAML (VS Code) The VS Code bundles have their definitions organized differently - VS Code has not yet fully implemented 2020-12 support, so it can not resolve non-local (ie not starting with `#/`) references correctly. The non-VS Code bundles were validated with [HyperJump][01]. [01]: https://json-schema.hyperjump.io/ This change also temporarily includes the gotstoy schema in the bundled output folder so you can review how the schema affects the authoring DevX. This change includes a bundle config file for determining which schemas should be bundled and how they should be named. While the outputs are committed here for convenience and reviewability, they should instead be generated with the build script and published as needed. They're build artifacts generated from the decomposed schema definitions. The build step doesn't support injecting links to the documentation, but we should add that functionality in the future. This would make it easier for authors and editors of configuration documents and resource manifests to look up the documentation without having to search for it.
This change rearranges the definitions for configuration parameters and resources so that only the valid parameter/resource definition in the `parameters` and `resources` properties are references. This makes the documentation and definition a little cleaner and easier to maintain. The validation properties are moved from definitions into the parameter document for the same reason - they aren not referenced anywhere else. In the resource instance schema, this change adds a validation pattern for the `dependsOn` key to match the proposed syntax. In the resource manifest schema, this change ensures that tags for a resource must be unique, disallowing repeated tags.
This change adds initial documentation for the configuration document and resource manifest schemas. It also documents the well-known property schemas so they can be referenced in the resource manifest docs.
This change prepares the repository and project for using the GitHub repository as the hosting location for the JSON Schemas. This change: - Moves the schemas out of the docs folder and into their own location - Updates the schema build script to generate a versioned output of the schemas that can be committed to the repository for external access in a reliable, coherent way. - Updates the schema build script to only export the schemas from source as JSON. - Updates the documentation to use the new canonical IDs for the schemas.
There was a problem hiding this comment.
These comments are from the viewpoint of shifting the winget API layer to align with this new schema. But I also think my suggestions apply broadly to tools/users reading configuration documents and reasoning about them without needing to have complete knowledge of all resources.
| The fully qualified type name of a resource uses the following syntax: | ||
|
|
||
| ```text | ||
| `<owner>[.<group>][.<area>]/<name>` |
There was a problem hiding this comment.
This doesn't have a collection or repository. It also doesn't contain any version information. If the goal is to have a fully qualified name, it feels to me like I should be able to take this string and be able to manifest the actual bits that it refers to (and inversely, all accessible sets of bits can be uniquely named).
I can understand if you don't really want a fully qualified name here, and thus excluding version seems reasonable. At a minimum I think it should support:
Repository/Module/Resource
But maybe I'm missing the point and the goal is purely about naming the resource (although even locally a version may be required to disambiguate).
Certainly, these things need to be definable somewhere in the resource object:
- Repository identity (name / some sort of universal identifier)
- Module identity (name + version selection [version / filtering options])
- Resource identity (name)
There was a problem hiding this comment.
^ @SteveL-MSFT - this is a good point worth talking through.
This syntax is, I think, borrowed from the ARM template syntax for resources and is roughly equivalent to the fully-qualified syntax for a PowerShell cmdlet, with a built-in model for namespacing.
The name of the resource is independent of the repository it comes from - the same resource could be published to multiple repositories - and instead identifies the resource itself. I do agree that it probably makes sense to extend this schema to include version, to disambiguate between two versions of the same resource already available.
There's some conversation in #47 about how to handle resource installation, but that's not currently handled by DSC itself. DSC expects that the resources are already installed/available prior to applying a configuration or invoking a resource.
In #92 I submitted a proposal for how we could handle DSC Resource registries, which I expect will be related to installing resources.
Co-authored-by: JohnMcPMS <johnmcp@microsoft.com>
Fix URI for `$schema` in config document enum
PR Summary
This change defines a set of JSON Schema documents for DSC. Instead of a few monolithic schema documents, this change defines the schemas as smaller, more manageable documents that can be bundled as needed.
These schemas are hand-authored and more specific than the schemas generated with the
dsc schemacommand. The schemas included here are implemented with loose validation, but we can support strict validation side-by-side.The schemas are organized into subfolders:
bundledfolder, the schema documents include a synthetic example of the bundling process. For this change, they were generated by hand, but they could be composed with tooling instead.configfolder, the schema documents validate a DSC Configuration document.definitionsfolder, the schema documents represent reused definitions for validation and/or documentation. Thetitleanddescriptionkeywords for instances in a JSON Schema are used by authoring tools to provide contextual documentation.outputsfolder, the schema documents represent the output users and integrating tools should expect from callingdsc. Tools may use these definitions to generate their own structs in their application code to more readily and accurately handle output from DSC.resourcefolder, themanifest*schema documents validate a command-based DSC Resource manifest.resource/propertiesfolder, the schema documents represent standard DSC Resource properties that have well-defined usage.The schema URL and the ID names for the schemas is best-effort but should not be treated as canonical without further discussion.
The documents include comments indicating ambiguities or questions that they raise.
This change includes a bundle config file for determining which schemas should be bundled and how they should be named. While the outputs are committed here for convenience and reviewability, they should instead be generated with the build script and published as needed. They're build artifacts generated from the decomposed schema definitions.
The build step doesn't support injecting links to the documentation, but we should add that functionality in the future. This would make it easier for authors and editors of configuration documents and resource manifests to look up the documentation without having to search for it.
PR Context
Useful schemas are required for users to begin implementing command-based DSC Resources and authoring test DSC Configuration documents. They're also required for us to document them. Defining the schemas helps to clarify functionality and purpose for me, as a tech writer.