feat: add JSON Schema support

secrecy/Cargo.toml

@@ -1,28 +1,34 @@
 [package]
-name        = "secrecy"
+name = "secrecy"
 description = """
 Wrapper types and traits for secret management which help ensure
 they aren't accidentally copied, logged, or otherwise exposed
 (as much as possible), and also ensure secrets are securely wiped
 from memory when dropped.
 """
-version     = "0.10.3"
-authors     = ["Tony Arcieri <tony@iqlusion.io>"]
-license     = "Apache-2.0 OR MIT"
-homepage    = "https://github.com/iqlusioninc/crates/"
-repository  = "https://github.com/iqlusioninc/crates/tree/main/secrecy"
-readme      = "README.md"
-categories  = ["cryptography", "memory-management", "no-std", "os"]
-keywords    = ["clear", "memory", "secret", "secure", "wipe"]
-edition     = "2021"
+version = "0.10.3"
+authors = ["Tony Arcieri <tony@iqlusion.io>"]
+license = "Apache-2.0 OR MIT"
+homepage = "https://github.com/iqlusioninc/crates/"
+repository = "https://github.com/iqlusioninc/crates/tree/main/secrecy"
+readme = "README.md"
+categories = ["cryptography", "memory-management", "no-std", "os"]
+keywords = ["clear", "memory", "secret", "secure", "wipe"]
+edition = "2021"
 rust-version = "1.60"
 
 [dependencies]
 zeroize = { version = "1.6", default-features = false, features = ["alloc"] }
 
 # optional dependencies
-serde = { version = "1", optional = true, default-features = false, features = ["alloc"] }
+serde = { version = "1", optional = true, default-features = false, features = [
+    "alloc",
+] }
+schemars = { version = "0.8.22", optional = true, default-features = false }
 
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
+
+[features]
+jsonschema = ["dep:schemars"]

secrecy/src/lib.rs

@@ -28,6 +28,14 @@
 //! does *not* receive a corresponding [`Serialize`] impl. If you would like
 //! types of `SecretBox<T>` to be serializable with `serde`, you will need to impl
 //! the [`SerializableSecret`] marker trait on `T`.
+//!
+//! # [JSON Schema](https://json-schema.org) support
+//!
+//! When the `jsonschema` feature of this crate is enabled, the [`SecretBox`] type
+//! will receive a [`JsonSchema`]
+//! ([schemars](https://docs.rs/schemars/latest/schemars/)) impl for all `SecretBox<T>`
+//! types where `T: JsonSchema`. This allows generating JSON Schema documents from
+//! types that are composed of `SecretBox<T>`, such as a configuration struct.
 
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
@@ -48,6 +56,16 @@ use zeroize::{Zeroize, ZeroizeOnDrop};
 #[cfg(feature = "serde")]
 use serde::{de, ser, Deserialize, Serialize};
 
+#[cfg(feature = "jsonschema")]
+use alloc::{
+    borrow::{Cow, ToOwned},
+    format,
+};
+#[cfg(feature = "jsonschema")]
+use core::{concat, module_path};
+#[cfg(feature = "jsonschema")]
+use schemars::{gen::SchemaGenerator, schema::Schema, JsonSchema};
+
 pub use zeroize;
 
 /// Wrapper type for values that contains secrets, which attempts to limit
@@ -335,6 +353,38 @@ where
     }
 }
 
+#[cfg(feature = "jsonschema")]
+impl JsonSchema for SecretString {
+    fn schema_name() -> String {
+        "SecretString".to_owned()
+    }
+    fn schema_id() -> Cow<'static, str> {
+        Cow::Borrowed(concat!(module_path!(), "::", "SecretString"))
+    }
+    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
+        generator.subschema_for::<String>()
+    }
+}
+
+#[cfg(feature = "jsonschema")]
+impl<T> JsonSchema for SecretBox<T>
+where
+    T: Zeroize + JsonSchema,
+{
+    fn schema_name() -> String {
+        format!("SecretBox_for_{}", T::schema_name())
+    }
+    fn schema_id() -> Cow<'static, str> {
+        Cow::Owned(alloc::format!(
+            concat!(module_path!(), "::", "SecretBox_for_{}"),
+            T::schema_id()
+        ))
+    }
+    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
+        generator.subschema_for::<T>()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::{ExposeSecret, SecretString};