(GH-642) Ensure camelCase for items in dsc_lib
#648
Merged
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
michaeltlombardi
force-pushed
the
gh-642/main/schema-casing-canonicalization
branch
2 times, most recently
from
22c034b to
7ffa476
Compare
Prior to this change, the structs and enums in `dsc_lib` didn't consistently use camelCase - most property names and enum values use camelCase, but not all - and this inconsistency isn't predictable for end users, who need to consult the JSON Schemas to be sure. This change updates the definitions to rename the fields and values when serializing and deserializing, which also updates their JSON Schema. A future change is required to update the canonical schemas in the repository to match these updates.
This change fixes a bug in the schema build script that caused the build to mangle the generated output by failing to correctly replace `.yaml` references to `.json`.
This change updates the YAML source definition files for the JSON Schemas to use the correct casing. It also adds the missing `context` property for the `Microsoft.DSC` metadata field.
This change generates the canonical schemas for in new folders: `v3`, `v3.0`, and `v3.0.0`, instead of the previous date-based folder `2024/04`. The changing of the casing is _not_ backwards compatible, and requires a new location to avoid breaking prior schemas. This change generates the schemas into three folders to accomodate the changes requested in PowerShell#138 for moving from date-based to semantic versioning for the schemas. Going forward, schema generation should: - Export to a folder for the current release with the full semantic version, like `v3.0.1` or `v3.1.0`. - Export to a folder for the current `major.minor` schema, like `v3.0` or `v3.1` - Build to a folder for the current major version of the release, like `v3`. Under this design, you can: - Get the exact version of the schema that a release shipped with by specifying the schema URI as `v<major>.<minor>.<patch>` - Get the latest schema for your minor version as `v<major>.<minor>` - Get the latest schema for your major version as `v<major>` Breaking changes to the schema have the potential to break integrating software, configuration documents, and resource manifests. They therefore constitute a breaking change in the application and require incrementing the major version segment of the semantic version. This change will be followed by an update to the allowed schema versions in the code itself, which should only recognize the updated schema at this time, not previous schemas.
This commit only touches the `dsc` and `dsc_lib` crates. A future commit will update the examples, manifests, and tests throughout the repository for the updated schema URIs. Tests against this commit specifically will not pass, but the changes to the library are broken out here for easier review. This change defines a new module in the library for interacting with and managing JSON Schemas for DSC. The code in this module is made public for use in other repository crates, but shouldn't be used by crates outside of this repository. It defines new enumerations: - `SchemaUriPrefix` for handling URIs pointing to either the GitHub repository or friendly `aka.ms` locations. - `SchemaForm` for the different forms the DSC schemas are published to (canonical, bundled, and enhanced for VS Code) - `RecognizedSchemaVersion` for managing the version folders schemas are publsihed to for and after GA. It defines a few helper functions for constructing the various URIs for a schema. These helper functions may be useful for testing, but should primarily be used through the new `DscRepoSchema` trait, which requires a type to define the base name and folder path for its schema and whether the schema should be published in its bundled form (only applies to top-level schemas, not subschemas). The trait provides default implementations for retrieving the schema URIs and a function to return a generated JSON Schema for the `$schema` keyword, used by both configuration documents and resource manifests. As we canonicalize and improve the schemas, this trait should make it simpler to manage the schemas across new versions and should be the container for JSON Schema enhancements specific to the DSC schemas. This change updates the configuration document and resource manifest definitions to implement the `DscRepoSchema` trait and replaces the per-type enumerations for schema version URIs by passing the `recognized_schema_uris_subschema` to the schemars `schema_with` attribute.
This change updates the schema URIs in the various resource manifests, configuration documents, and tests to use the new schema URIs: - `https://aka.ms/dsc/schemas/v3/bundled/config/document.json` for configuration documents. - `https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json` for resource manifests. This change pins the changes to the major version to reduce how often these files need to be updated with future releases. It uses the `aka.ms` prefix instead of the GitHub URI prefix for readability and because we expect the majority of users to prefer the shorter URI. With this change in place, tests broken in the previous commit should pass again.
Prior to this change, DSC didn't have a convenient way to verify whether a configuration or manifest used a recognized schema or to switch behaviors based on the declared URI. This change begins the process of plumbing the recognized schemas into DSC so the engine can correctly validate and handle items based on the value of the `$schema` keyword. In this first iteration, the `DscRepoSchema` trait adds a method to validate whether the item uses a recognized schema. In the future, the engine should provide further handling than pass/fail. This change only adds the methods, it doesn't alter how DSC processes configuration documents or resource manifests.
…/config ref This change drafts a new reference document that explains how the DSC schemas are published, the URIs DSC recognizes for those schemas, and updates the documentation for the resource manifest and configuration document schemas with the updated context. A future change will address updating the rest of the reference documentation.
This change updates the reference documentation to align with the new schema URIs and the changes to the enumeration and struct casing.
michaeltlombardi
force-pushed
the
gh-642/main/schema-casing-canonicalization
branch
2 times, most recently
from
312c9a9 to
712b4f9
Compare
michaeltlombardi
force-pushed
the
gh-642/main/schema-casing-canonicalization
branch
from
712b4f9 to
10e96aa
Compare
|
Reviewers - this PR touches a lot of files because of the schema updates. I would strongly recommend reviewing the changes by commit rather in total - I tried to break the change up across commits to be easier to follow and review. This PR may be worth reviewing synchronously, as it touches on how we publish schemas for GA and afterward. I tried to describe the model in a new reference document and the code comments wherever possible. I don't mind owning the schemas and related tooling. I've been enjoying the work and have some ideas for how I can make it easier to maintain the reference docs once we canonicalize the schemas in |
SteveL-MSFT
requested changes
Feb 25, 2025
SteveL-MSFT
approved these changes
Feb 25, 2025
Merged
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 updates the definitions to rename the fields and values to use camelCase when serializing and deserializing, which also updates their JSON Schema.
TODO:
Add tests to generically verify serialized data types use camelCase (optional)- deferred to future PRPR Context
Prior to this change, the structs and enums in
dsc_libdidn't consistently use camelCase - most property names and enum values use camelCase, but not all - and this inconsistency isn't predictable for end users, who need to consult the JSON Schemas to be sure.Fix #642