Canonicalize registry resource schema #582
Draft
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.