-
Notifications
You must be signed in to change notification settings - Fork 32
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Canonicalize registry resource schema #582
Draft
michaeltlombardi
wants to merge
3
commits into
PowerShell:main
Choose a base branch
from
michaeltlombardi:schema/main/canonicalizing-prototype
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Canonicalize registry resource schema #582
michaeltlombardi
wants to merge
3
commits into
PowerShell:main
from
michaeltlombardi:schema/main/canonicalizing-prototype
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
1c29a32
to
3140b71
Compare
This change prototypes shifting from separately maintained schemas in the `schemas` folder to deriving fully expressed schemas from the Rust structs in the code. Doing so requires using the alpha release of schemars v1, which added support for more easily defining schemas using attributes and supports deriving schemas adhering to the JSON Schema 2020-12 specification. Of particular note are the following changes to the JSON Schema for instances of the registry resource: - Use JSON Schema specification draft 2020-12 instead of draft 07. - Added `title` and `description` for every property as documentation. - Added a regular expression check for `keyPath` to ensure it starts with a valid hive identifier. - Added the `$id` keyword to ensure that users and integrating developers can get a copy of the schema online instead of always calling the command. - Marked the `keyPath` property as required. - Marked the `valueName` property as required _only when_ `valueData` is specified. - Marked the `_metadata` property and its `whatIf` sub-property as read-only. - Defined the default value for the `_exist` property as `true`. In the process of implementing this prototype, this change also addressed a few related challenges: - In order to define longer strings for documentation keywords in the schemas, this change uses the `rust_i18n` library to provide a way to map complex or lengthy strings to key names. This also prepares the project for internationalization and localization, though the change only defines translations for English. - To minimize rework, the struct attributes define the JSON Schema with VS Code's annotation keywords, which enhance the authoring and editing experience in VS Code, but are generally ignored by other tools and libraries. To account for the difference between the canonical (stictly 2020-12 compatible) schema and the enhanced schema this change also: 1. Adds the `--enhanced` option to the `registry schema` command to enable returning the enhanced schema, but default to returning the canonical schema as is current behavior. 1. Defines the `remove_vscode_keywords` function to recursively remove those keywords. While the function is implemented in the registry resource in this prototyping PR, it better belongs in `dsc_lib`. 1. Defines the `get_schema_generator` function to return a generator with the correct settings for canonical and enhanced schemas. In both cases, it no longer adds the `null` type for optional items in the struct to better conform with JSON Schema. In JSON Schema, specifying `null` for a property value is _not_ semantically the same as _not_ specifying the property. For the enhanced schemas, it also uses `definitions` instead of `$defs`, as VS Code doesn't understand retrieving references from `$defs`. This change shows how we can begin to: 1. Define full, enhanced JSON schemas for data types in Rust and export those schemas in both canonical and enhanced variants. 1. Migrate from in-code strings to referencing data keys, making it easier to change documentation and messages without editing the code and preparing the projects for internationalization and localization. 1. Define reusable helpers for the projects to minimize rework. The scope of these changes is limited to the registry project only.
This change exports the registry schemas to the repository for online review without requiring a user or integrating developer to install the package and invoke the `registry schema` command.
3140b71
to
f1a1fcc
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR Summary
This change prototypes shifting from separately maintained schemas in the
schemas
folder to deriving fully expressed schemas from the Rust structs in the code. This change shows how we can begin to:PR Context
Deriving more descriptive schemas from the structs required using the alpha release of schemars v1, which added support for more easily defining schemas using attributes and supports deriving schemas adhering to the JSON Schema 2020-12 specification.
Of particular note are the following changes to the JSON Schema for instances of the registry resource:
title
anddescription
for every property as documentation.keyPath
to ensure it starts with a valid hive identifier.$id
keyword to ensure that users and integrating developers can get a copy of the schema online instead of always calling the command.keyPath
property as required.valueName
property as required only whenvalueData
is specified._metadata
property and itswhatIf
sub-property as read-only._exist
property astrue
.In the process of implementing this prototype, this change also addressed a few related challenges:
In order to define longer strings for documentation keywords in the schemas, this change uses the
rust_i18n
library to provide a way to map complex or lengthy strings to key names. This also prepares the project for internationalization and localization, though the change only defines translations for English.To minimize rework, the struct attributes define the JSON Schema with VS Code's annotation keywords, which enhance the authoring and editing experience in VS Code, but are generally ignored by other tools and libraries. To account for the difference between the canonical (stictly 2020-12 compatible) schema and the enhanced schema this change also:
--enhanced
option to theregistry schema
command to enable returning the enhanced schema, but default to returning the canonical schema as is current behavior.remove_vscode_keywords
function to recursively remove those keywords. While the function is implemented in the registry resource in this prototyping PR, it better belongs indsc_lib
.get_schema_generator
function to return a generator with the correct settings for canonical and enhanced schemas. In both cases, it no longer adds thenull
type for optional items in the struct to better conform with JSON Schema. In JSON Schema, specifyingnull
for a property value is not semantically the same as not specifying the property. For the enhanced schemas, it also usesdefinitions
instead of$defs
, as VS Code doesn't understand retrieving references from$defs
.The scope of these changes is limited to the registry project only.