(GH-538) Define VS Code extended vocabulary and dialect

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.

Author: michaeltlombardi

Cargo.lock

@@ -200,7 +200,7 @@ utfx = { version = "0.1" }
 uuid = { version = "1.18", features = ["v4"] }
 # dsc-lib, dsc-lib-jsonschema
 url = { version = "2.5" }
-# dsc-lib
+# dsc-lib, dsc-lib-jsonschema
 urlencoding = { version = "2.1" }
 # dsc-lib
 which = { version = "8.0" }

Cargo.toml

@@ -0,0 +1 @@
+doc-valid-idents = ["IntelliSense", ".."]

lib/dsc-lib-jsonschema/.clippy.toml

@@ -7,13 +7,15 @@ edition = "2024"
 doctest = false # Disable doc tests by default for compilation speed
 
 [dependencies]
+jsonschema = { workspace = true }
 regex = { workspace = true }
 rust-i18n = { workspace = true }
 schemars = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 tracing = { workspace = true }
 url = { workspace = true }
+urlencoding = { workspace = true }
 
 [dev-dependencies]
 # Helps review complex comparisons, like schemas

lib/dsc-lib-jsonschema/Cargo.toml

@@ -112,3 +112,56 @@ invalid item: %{invalid_item}
 
 transforming schema: %{transforming_schema}
 """
+
+[vscode.keywords.allow_comments]
+factory_error_invalid_type = "The 'allowComments' VS Code keyword must be a boolean value."
+
+[vscode.keywords.allow_trailing_commas]
+factory_error_invalid_type = "The 'allowTrailingCommas' VS Code keyword must be a boolean value."
+
+[vscode.keywords.completion_detail]
+factory_error_invalid_type = "The 'completionDetail' VS Code keyword must be a string value."
+
+[vscode.keywords.default_snippets]
+factory_error_suffix = "The 'defaultSnippets' VS Code keyword must be an array of objects. Every object must be a valid snippet definition."
+factory_error_not_array = "Non-array value is invalid."
+factory_error_invalid_item = "Invalid definition for an object in the array."
+factory_error_non_object_item = "Array containing non-object items is invalid."
+
+[vscode.keywords.deprecation_message]
+factory_error_invalid_type = "The 'deprecationMessage' VS Code keyword must be a string value."
+
+[vscode.keywords.do_not_suggest]
+factory_error_invalid_type = "The 'doNotSuggest' VS Code keyword must be a boolean value."
+
+[vscode.keywords.enum_descriptions]
+factory_error_suffix = "The 'enumDescriptions' VS Code keyword must be an array of string values. The 'enumDescriptions' keyword should have the same number of items as the 'enum' keyword."
+factory_error_not_array = "Non-array value is invalid."
+factory_error_non_string_item = "Array containing non-string items is invalid."
+
+[vscode.keywords.enum_details]
+factory_error_suffix = "The 'enumDetails' VS Code keyword must be an array of string values. The 'enumDetails' keyword should have the same number of items as the 'enum' keyword."
+factory_error_not_array = "Non-array value is invalid."
+factory_error_non_string_item = "Array containing non-string items is invalid."
+
+[vscode.keywords.enum_sort_texts]
+factory_error_suffix = "The 'enumSortTexts' VS Code keyword must be an array of string values. The 'enumSortTexts' keyword should have the same number of items as the 'enum' keyword."
+factory_error_not_array = "Non-array value is invalid."
+factory_error_non_string_item = "Array containing non-string items is invalid."
+
+[vscode.keywords.error_message]
+factory_error_invalid_type = "The 'errorMessage' VS Code keyword must be a string value."
+
+[vscode.keywords.markdown_description]
+factory_error_invalid_type = "The 'markdownDescription' VS Code keyword must be a string value."
+
+[vscode.keywords.markdown_enum_descriptions]
+factory_error_suffix = "The 'markdownEnumDescriptions' VS Code keyword must be an array of string values. The 'markdownEnumDescriptions' keyword should have the same number of items as the 'enum' keyword."
+factory_error_not_array = "Non-array value is invalid."
+factory_error_non_string_item = "Array containing non-string items is invalid."
+
+[vscode.keywords.pattern_error_message]
+factory_error_invalid_type = "The 'allowTrailingCommas' VS Code keyword must be a string value."
+
+[vscode.keywords.suggest_sort_text]
+factory_error_invalid_type = "The 'allowTrailingCommas' VS Code keyword must be a string value."