(GH-538) Add get_keyword_as_subschema extension methods

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.

Author: michaeltlombardi

lib/dsc-lib-jsonschema/src/schema_utility_extensions.rs

@@ -10,7 +10,7 @@
 //!
 //! The rest of the utility methods work with specific keywords, like `$id` and `$defs`.
 
-use core::{clone::Clone, iter::Iterator, option::Option::None};
+use core::{clone::Clone, convert::TryInto, iter::Iterator, option::Option::None};
 use std::string::String;
 
 use schemars::Schema;
@@ -537,6 +537,103 @@ pub trait SchemaUtilityExtensions {
     /// )
     /// ```
     fn get_keyword_as_string(&self, key: &str) -> Option<String>;
+    /// Checks a JSON Schema for a given keyword and returns the value of that  keyword, if it
+    /// exists, as a [`Schema`].
+    ///
+    /// If the keyword doesn't exist or isn't a subchema, this function returns [`None`].
+    ///
+    /// # Examples
+    ///
+    /// When the given keyword exists and is a subschema, the function returns the subschema.
+    ///
+    /// ```rust
+    /// use schemars::json_schema;
+    /// use dsc_lib_jsonschema::schema_utility_extensions::SchemaUtilityExtensions;
+    ///
+    /// let ref schema = json_schema!({
+    ///     "type": "array",
+    ///     "items": {
+    ///         "type": "string"
+    ///     }
+    /// });
+    /// assert_eq!(
+    ///     schema.get_keyword_as_subschema("items"),
+    ///     Some(&json_schema!({"type": "string"}))
+    /// );
+    /// ```
+    ///
+    /// When the given keyword doesn't exist or has the wrong data type, the function returns
+    /// [`None`].
+    ///
+    /// ```rust
+    /// use schemars::json_schema;
+    /// use dsc_lib_jsonschema::schema_utility_extensions::SchemaUtilityExtensions;
+    ///
+    /// let ref schema = json_schema!({
+    ///     "items": "invalid"
+    /// });
+    ///
+    /// assert_eq!(
+    ///     schema.get_keyword_as_subschema("not_exist"),
+    ///     None
+    /// );
+    ///
+    /// assert_eq!(
+    ///     schema.get_keyword_as_subschema("items"),
+    ///     None
+    /// )
+    /// ```
+    fn get_keyword_as_subschema(&self, key: &str) -> Option<&Schema>;
+    /// Checks a JSON Schema for a given keyword and mutably borrows the value of that keyword,
+    /// if it exists, as a [`Schema`].
+    ///
+    /// If the keyword doesn't exist or isn't a subschema, this function returns [`None`].
+    ///
+    /// # Examples
+    ///
+    /// When the given keyword exists and is a subschema, the function returns the subschema.
+    ///
+    /// ```rust
+    /// use schemars::json_schema;
+    /// use serde_json::json;
+    /// use dsc_lib_jsonschema::schema_utility_extensions::SchemaUtilityExtensions;
+    ///
+    /// let ref mut subschema = json_schema!({
+    ///     "type": "string"
+    /// });
+    /// let ref mut schema = json_schema!({
+    ///     "type": "array",
+    ///     "items": subschema
+    /// });
+    /// assert_eq!(
+    ///     schema.get_keyword_as_subschema_mut("items"),
+    ///     Some(subschema)
+    /// );
+    /// ```
+    ///
+    /// When the given keyword doesn't exist or has the wrong data type, the function returns
+    /// [`None`].
+    ///
+    /// ```rust
+    /// use schemars::json_schema;
+    /// use serde_json::json;
+    /// use dsc_lib_jsonschema::schema_utility_extensions::SchemaUtilityExtensions;
+    ///
+    /// let ref mut schema = json_schema!({
+    ///     "items": "invalid"
+    /// });
+    ///
+    /// assert_eq!(
+    ///     schema.get_keyword_as_object_mut("not_exist"),
+    ///     None
+    /// );
+    ///
+    /// assert_eq!(
+    ///     schema.get_keyword_as_object_mut("items"),
+    ///     None
+    /// )
+    /// ```
+    fn get_keyword_as_subschema_mut(&mut self, key: &str) -> Option<&mut Schema>;
     /// Checks a JSON schema for a given keyword and returns the value of that keyword, if it
     /// exists, as a [`u64`].
     ///
@@ -1222,6 +1319,14 @@ impl SchemaUtilityExtensions for Schema {
             .and_then(Value::as_str)
             .map(std::string::ToString::to_string)
     }
+    fn get_keyword_as_subschema(&self, key: &str) -> Option<&Schema> {
+        self.get(key)
+            .and_then(|v| <&Value as TryInto<&Schema>>::try_into(v).ok())
+    }
+    fn get_keyword_as_subschema_mut(&mut self, key: &str) -> Option<&mut Schema> {
+        self.get_mut(key)
+            .and_then(|v| <&mut Value as TryInto<&mut Schema>>::try_into(v).ok())
+    }
     fn get_keyword_as_u64(&self, key: &str) -> Option<u64> {
         self.get(key)
             .and_then(Value::as_u64)

lib/dsc-lib-jsonschema/src/tests/schema_utility_extensions/mod.rs

@@ -26,6 +26,9 @@ static OBJECT_VALUE: LazyLock<Map<String, Value>> = LazyLock::new(|| json!({
 }).as_object().unwrap().clone());
 static NULL_VALUE:    ()   = ();
 static STRING_VALUE: &str  = "value";
+static SUBSCHEMA_VALUE: LazyLock<Schema> = LazyLock::new(|| json_schema!({
+    "$id": "https://schema.contoso.com/test/get_keyword_as/subschema.json"
+}));
 static TEST_SCHEMA: LazyLock<Schema> = LazyLock::new(|| json_schema!({
     "$id": "https://schema.contoso.com/test/get_keyword_as.json",
     "array": *ARRAY_VALUE,
@@ -35,6 +38,7 @@ static TEST_SCHEMA: LazyLock<Schema> = LazyLock::new(|| json_schema!({
     "object": *OBJECT_VALUE,
     "null": null,
     "string": *STRING_VALUE,
+    "subschema": *SUBSCHEMA_VALUE,
 }));
 
 /// Defines test cases for a given `get_keyword_as` function (non-mutable).
@@ -135,12 +139,14 @@ test_cases_for_get_keyword_as!(
     get_keyword_as_number: "array", "integer", Some(&(INTEGER_VALUE.into())),
     get_keyword_as_str: "array", "string", Some(STRING_VALUE),
     get_keyword_as_string: "array", "string", Some(STRING_VALUE.to_string()),
+    get_keyword_as_subschema: "array", "subschema", Some(&*SUBSCHEMA_VALUE),
 );
 
 
 test_cases_for_get_keyword_as_mut!(
     get_keyword_as_array_mut: "boolean", "array", Some(&mut (*ARRAY_VALUE).clone()),
     get_keyword_as_object_mut: "array", "object", Some(&mut (*OBJECT_VALUE).clone()),
+    get_keyword_as_subschema_mut: "array", "subschema", Some(&mut (*SUBSCHEMA_VALUE).clone()),
 );
 
 #[cfg(test)] mod get_id {