Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Canonicalize registry resource schema#582

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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Draft
michaeltlombardi wants to merge3 commits intoPowerShell:main
base:main
Choose a base branch
Loading
frommichaeltlombardi:schema/main/canonicalizing-prototype

Conversation

michaeltlombardi
Copy link
Collaborator

PR Summary

This change prototypes shifting from separately maintained schemas in theschemas folder to deriving fully expressed schemas from the Rust structs in the code. 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.
  2. 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.
  3. Define reusable helpers for the projects to minimize rework.

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:

  • Use JSON Schema specification draft 2020-12 instead of draft 07.
  • Addedtitle anddescription for every property as documentation.
  • Added a regular expression check forkeyPath 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 thekeyPath property as required.
  • Marked thevalueName property as requiredonly whenvalueData is specified.
  • Marked the_metadata property and itswhatIf sub-property as read-only.
  • Defined the default value for the_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 therust_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 theregistry schema command to enable returning the enhanced schema, but default to returning the canonical schema as is current behavior.
    2. Defines theremove_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.
    3. Defines theget_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 isnot semantically the same asnot 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.

@michaeltlombardimichaeltlombardiforce-pushed theschema/main/canonicalizing-prototype branch from1c29a32 to3140b71CompareOctober 24, 2024 20:58
This change prototypes shifting from separately maintained schemas inthe `schemas` folder to deriving fully expressed schemas from the Ruststructs in the code.Doing so requires using the alpha release of schemars v1, which addedsupport for more easily defining schemas using attributes and supportsderiving schemas adhering to the JSON Schema 2020-12  specification.Of particular note are the following changes to the JSON Schema forinstances 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 alsoaddressed 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 onlinereview without requiring a user or integrating developer to installthe package and invoke the `registry schema` command.
@michaeltlombardimichaeltlombardiforce-pushed theschema/main/canonicalizing-prototype branch from3140b71 tof1a1fccCompareOctober 29, 2024 13:29
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

1 participant
@michaeltlombardi

[8]ページ先頭

©2009-2025 Movatter.jp