Skip to content

Conversation

@michaeltlombardi
Copy link
Collaborator

PR Summary

This change defines the SchemaUtilityExtensions trait in the dsc-lib-jsonschema crate to provide useful shorthand methods for the schemars::Schema type when munging and transforming schemas.

This change:

PR Context

While the trait includes some methods I expect to be useful, it doesn't try to fully map methods for retrieving every keyword. Instead, it primarily simplifies working with the following keywords:

  • $id to retrieve and set the identifier for a schema.
  • $defs to retrieve and munge referenced subschemas.
  • properties to retrieve and munge property definitions.

The trait does define generic methods for retrieving keywords with an expected type, like get_keyword_as_object() and get_keyword_as_str. These are convenience methods to replace always calling code like the following when you want to retrieve a keyword with a known type:

let ref schema = json_schema!({
    "title": "Schema title"
});
if let Some(title) = schema.get("title").and_then(|v| v.as_str()) {
    println!("Schema title is {title}");
}

So you can instead do:

let ref schema = json_schema!({
    "title": "Schema title"
});
if let Some(title) = schema.get_keyword_as_str("title") {
    println!("Schema title is {title}");
}

@michaeltlombardi
Copy link
Collaborator Author

After #1171 is merged, I'll rebase this PR prior to final review and merge.

@michaeltlombardi michaeltlombardi force-pushed the gh-538/main/extension-methods branch 4 times, most recently from bcc9cf6 to 970dd4e Compare October 21, 2025 21:18
@SteveL-MSFT
Copy link
Member

@michaeltlombardi can you rebase off main so I can see just the delta?

@michaeltlombardi
Copy link
Collaborator Author

@SteveL-MSFT - I don't think so, because these changes build on the dsc-lib-jsonschema crate.

But all the changes for this PR (on top of #1171) are in this commit:

970dd4e

This change begins the schema canonicalization process by
adding a new library crate to contain the helpers for
defining canonical and enhanced schemas ergonomically.

In this initial phase, the new crate defines:

- The `VSCODE_KEYWORDS` constant, enumerating the keywords
  that VS Code's JSON language server recognizes.
- The `idiomaticize_string_enum` transformer for munging the
  generated schemas for string enums with annotation keywords.
- The `idiomaticize_externally_tagged_enum` transformer for
  munging the generated schemas for externally tagged enums
  to a more idiomatic and readable representation.
This change uses the new `idiomaticize_*` transformers from the
`dsc-lib-jsonschema` crate in the `dsc-lib` crate to ensure that
the generated schemas are idiomatic.
This change updates the i18n Pester tests to account for:

- Usage of the `t!` macro when the translation key is defined on the next line.
- Usage of the convenience `panic_t!` macro, which simplifies sending translated
  strings to the `panic!` macro.
- Usage of the convenience `assert_t!` macro, which simplifies sending translated
  strings to the panic when an `assert!` macro fails.

These use cases were required for the `dsc-lib-jsonschema` crate, which uses both
`panic_t!` and `assert_t!` to raise translated panic messages when a transform is
invalidly applied.

While this change doesn't modify the behavior for any other crates, it does lay the
groundwork for translating panic messages and assertions throughout the crates.
This change defines the `SchemaUtilityExtensions` trait in the
`dsc-lib-jsonschema` crate to provide useful shorthand methods for the
`schemars::Schema` type when munging and transforming schemas.

While the trait includes some methods I expect to be useful, it doesn't
try to fully map methods for retrieving every keyword. Instead, it
primarily simplifies working with the following keywords:

- `$id` to retrieve and set the identifier for a schema.
- `$defs` to retrieve and munge referenced subschemas.
- `properties` to retrieve and munge property definitions.

The trait _does_ define generic methods for retrieving keywords with an
expected type, like `get_keyword_as_object()` and `get_keyword_as_str`.
These are convenience methods to replace always calling code like the
following when you want to retrieve a keyword with a known type:

```rust
let ref schema = json_schema!({
    "title": "Schema title"
});
if let Some(title) = schema.get("title").and_then(|v| v.as_str()) {
    println!("Schema title is {title}");
}
```

So you can instead do:

```rust
let ref schema = json_schema!({
    "title": "Schema title"
});
if let Some(title) = schema.get_keyword_as_str("title") {
    println!("Schema title is {title}");
}
```

This change:

- Defines and implements the trait, providing documentation for every
  new method.
- Adds tests for the behaviors of every extension method.
@michaeltlombardi michaeltlombardi force-pushed the gh-538/main/extension-methods branch from 970dd4e to 62221fc Compare October 22, 2025 12:16
@SteveL-MSFT SteveL-MSFT added this pull request to the merge queue Oct 22, 2025
Merged via the queue into PowerShell:main with commit 2cac42a Oct 22, 2025
19 checks passed
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.

2 participants