Skip to content
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
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

michaeltlombardi
Copy link
Collaborator

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:

  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.
  • 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.
    2. 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.
    3. 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.

The scope of these changes is limited to the registry project only.

@michaeltlombardi michaeltlombardi force-pushed the schema/main/canonicalizing-prototype branch from 1c29a32 to 3140b71 Compare October 24, 2024 20:58
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.
@michaeltlombardi michaeltlombardi force-pushed the schema/main/canonicalizing-prototype branch from 3140b71 to f1a1fcc Compare October 29, 2024 13:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant