(GH-538) Add VS Code keywords, vocabulary, and dialect to dsc-lib-jsonschema
#1276
+6,920
−658
Conversation
This file contains hidden or 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
Prior to this change, the `dsc-lib-jsonschema` crate defined extension methods for schemas to retrieve keywords as various underlying data types when the caller knows the data type they need. However, the extension methods didn't include a way to retrieve values as _schemas_, so any use of those values requires the caller to reimplement the extension methods logic or to manually convert the value to a schema. This change adds two helper methods to retrieve a keyword as a `schemars::Schema` instance (borrowed and mutably borrowed) to make working with subschemas more ergonomic.
This change: - Updates the following functions to return instances of `schemars::Schema` instead of `Map<String, Value>`, since the returned data is _always_ a subschema, if it exists: - `get_defs_subschema_from_id()` - `get_defs_subschema_from_id_mut()` - `get_defs_subschema_from_reference()` - `get_defs_subschema_from_reference_mut()` - `get_property_subschema()` - `get_property_subschema_mut()` - Removes the type aliases `Object` (for `Map<String, Value>`) and `Array` (for `Vec<Value>`), as these conveniences weren't saving much typing and Rust Analyzer wasn't always plumbing them through for IntelliSense. The uses of these aliases now revert to calling the underlying types. - Updates documentation and tests for the modified functions.
This change refactors the `dsc-lib-jsonschema` library without modifying any behavior. This change: - Splits the functions in the `transforms` module out into submodules and re-exports them from `transforms` - this keeps referencing the functions the way it was before but makes it easier to navigate the files, given their length. - Makes the unit tests for `schema_utility_extensions` mirror the structure from the source code. - Makes the integration tests for `transform` mirror the structure from the source code.
This change: - Updates the following functions to return instances of `schemars::Schema` instead of `Map<String, Value>`, since the returned data is _always_ a subschema, if it exists: - `get_defs_subschema_from_id()` - `get_defs_subschema_from_id_mut()` - `get_defs_subschema_from_reference()` - `get_defs_subschema_from_reference_mut()` - `get_property_subschema()` - `get_property_subschema_mut()` - Removes the type aliases `Object` (for `Map<String, Value>`) and `Array` (for `Vec<Value>`), as these conveniences weren't saving much typing and Rust Analyzer wasn't always plumbing them through for IntelliSense. The uses of these aliases now revert to calling the underlying types. - Updates documentation and tests for the modified functions.
This change addresses the need for parsing, validating, and processing
the custom JSON Schema keywords that VS Code recognizes for use in the
DSC schemas and resource schemas.
This change:
- Defines every custom keyword that the VS Code language server for JSON
recognizes as custom keywords in the `jsonschema` crate so that we can
correctly validate schemas that use those keywords programmatically.
The implementation in `jsonschema` is primarily intended for custom
validation keywords. Every custom keyword that VS Code recognizes is
an annotation keyword. They don't affect validation for instances of
data. This implementation ensures that we can parse those keywords for
our own use and validate that our schema definitions correctly define
values for those keywords.
- Defines the VS Code vocabulary, which includes the keywords. This
enables us to define our own dialects which recognize the VS Code
keywords.
- Defines a VS Code dialect, which includes the Draft 2020-12
vocabularies and the VS Code vocabulary.
- Defines the `VSCodeKeyword` enum for easier selection of keywords,
given that you can't ergonomically or safely pass a _type_ in Rust
functions.
This replaces the previous `VSCODE_KEYWORDS` struct.
- Updates the `idiomaticize_externally_tagged_enum` transform function
to use the `VSCodeKeyword` enum now that `VSCODE_KEYWORDS` is removed.
- Defines extension methods for the `ValidationOptions` struct from the
`jsonschema` crate to make adding VS Code keywords, vocabulary, and
dialect simpler and more ergonomic, participating in the builder
pattern that `jsonschema` uses when creating a validator.
- Defines extension methods for the `Schema` struct from the `schemars`
crate to simplify working with VS COde keywords in schemas, such as
retrieving the value for a keyword or checking whether the schema
uses the VS Code dialect.
- Adds three new extension methods to the `SchemaUtilityExtensions`
trait:
- `get_bundled_schema_resource_ids`, which retrieves the value of
the `$id` keyword from entries in the `$defs` keyword, each of which
represents a bundled schema resource.
- `get_references`, which recursively retrieves the value for every
`$ref` keyword in the schema.
- `replace_references`, which recursively replaces the value of the
`$ref` keyword from a given value to a new one specified by the
caller.
- `reference_is_for_bundled_resource`, which indicates whether a given
value for a `$ref` keyword points to a bundled schema resource in
the `$defs` keyword for the schema.
This change lays the groundwork for incorporating the VS Code keywords
into the schemas generated from Rust code and for defining our own
vocabulary for DSC as needed.
michaeltlombardi
changed the title
dsc-lib-jsonschema
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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
Important
This change is a continuation of the work in #1226. It shouldn't be merged until those changes are approved and merged. Until then, I'm leaving this PR in draft.
This change:
Defines every custom keyword that the VS Code language server for JSON recognizes as custom keywords in the
jsonschemacrate so that we can correctly validate schemas that use those keywords programmatically.The implementation in
jsonschemais primarily intended for custom validation keywords. Every custom keyword that VS Code recognizes is an annotation keyword. They don't affect validation for instances of data. This implementation ensures that we can parse those keywords for our own use and validate that our schema definitions correctly define values for those keywords.Defines the VS Code vocabulary, which includes the keywords. This enables us to define our own dialects which recognize the VS Code keywords.
Defines a VS Code dialect, which includes the Draft 2020-12 vocabularies and the VS Code vocabulary.
Defines the
VSCodeKeywordenum for easier selection of keywords, given that you can't ergonomically or safely pass a type in Rust functions.This replaces the previous
VSCODE_KEYWORDSstruct.Updates the
idiomaticize_externally_tagged_enumtransform function to use theVSCodeKeywordenum now thatVSCODE_KEYWORDSis removed.Defines extension methods for the
ValidationOptionsstruct from thejsonschemacrate to make adding VS Code keywords, vocabulary, and dialect simpler and more ergonomic, participating in the builder pattern thatjsonschemauses when creating a validator.Defines extension methods for the
Schemastruct from theschemarscrate to simplify working with VS COde keywords in schemas, such as retrieving the value for a keyword or checking whether the schema uses the VS Code dialect.Adds three new extension methods to the
SchemaUtilityExtensionstrait:get_bundled_schema_resource_ids, which retrieves the value of the$idkeyword from entries in the$defskeyword, each of which represents a bundled schema resource.get_references, which recursively retrieves the value for every$refkeyword in the schema.replace_references, which recursively replaces the value of the$refkeyword from a given value to a new one specified by the caller.reference_is_for_bundled_resource, which indicates whether a given value for a$refkeyword points to a bundled schema resource in the$defskeyword for the schema.PR Context
This change addresses the need for parsing, validating, and processing the custom JSON Schema keywords that VS Code recognizes for use in the DSC schemas and resource schemas. This change lays the groundwork for incorporating the VS Code keywords into the schemas generated from Rust code and for defining our own vocabulary for DSC as needed.