Schema generation (#178)

.github/workflows/rust.yml

@@ -43,6 +43,7 @@ jobs:
         cargo check --no-default-features --features docs
         cargo check --no-default-features --features serde
         cargo check --no-default-features --features serde,decode
+        cargo check --no-default-features --features schema
 
     - name: build
       run: |

Cargo.toml

@@ -21,6 +21,7 @@ scale-info-derive = { version = "2.5.0", path = "derive", default-features = fal
 serde = { version = "1", default-features = false, optional = true, features = ["derive", "alloc"] }
 derive_more = { version = "0.99.1", default-features = false, features = ["from"] }
 scale = { package = "parity-scale-codec", version = "3", default-features = false, features = ["derive"] }
+schemars = { version = "0.8", optional = true }
 
 [features]
 default = ["std"]
@@ -35,14 +36,19 @@ derive = [
 docs = [
     "scale-info-derive/docs"
 ]
-# enables decoding and deserialization of portable scale-info type metadata
+# Enables decoding and deserialization of portable scale-info type metadata.
 decode = [
     "scale/full"
 ]
-# enables type information for bitvec types, matching the name of the parity-scale-codec feature
+# Enables type information for bitvec types, matching the name of the parity-scale-codec feature.
 bit-vec = [
     "bitvec"
 ]
+# Enables JSON Schema generation.
+schema = [
+    "std",
+    "schemars"
+]
 
 [workspace]
 members = [

src/form.rs

@@ -39,25 +39,42 @@ use crate::{
     meta_type::MetaType,
 };
 
+#[cfg(feature = "schema")]
+use schemars::JsonSchema;
 #[cfg(feature = "serde")]
 use serde::Serialize;
 
+/// Trait to support derivation of `JsonSchema` for schema generation.
+#[cfg(feature = "schema")]
+pub trait JsonSchemaMaybe: JsonSchema {}
+/// Trait to support derivation of `JsonSchema` for schema generation.
+#[cfg(not(feature = "schema"))]
+pub trait JsonSchemaMaybe {}
+
 /// Trait to control the internal structures of type definitions.
 ///
 /// This allows for type-level separation between free forms that can be
 /// instantiated out of the flux and portable forms that require some sort of
 /// interning data structures.
 pub trait Form {
     /// The type representing the type.
-    type Type: PartialEq + Eq + PartialOrd + Ord + Clone + Debug;
+    type Type: PartialEq + Eq + PartialOrd + Ord + Clone + Debug + JsonSchemaMaybe;
     /// The string type.
-    type String: AsRef<str> + PartialEq + Eq + PartialOrd + Ord + Clone + Debug;
+    type String: AsRef<str>
+        + PartialEq
+        + Eq
+        + PartialOrd
+        + Ord
+        + Clone
+        + Debug
+        + JsonSchemaMaybe;
 }
 
 /// A meta meta-type.
 ///
 /// Allows to be converted into other forms such as portable form
 /// through the registry and `IntoPortable`.
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Debug)]
 pub enum MetaForm {}
@@ -74,6 +91,7 @@ impl Form for MetaForm {
 /// This resolves some lifetime issues with self-referential structs (such as
 /// the registry itself) but can no longer be used to resolve to the original
 /// underlying data.
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Debug)]
 pub enum PortableForm {}
@@ -92,3 +110,9 @@ cfg_if::cfg_if! {
         }
     }
 }
+
+// Blanket implementations
+#[cfg(not(feature = "schema"))]
+impl<T> JsonSchemaMaybe for T {}
+#[cfg(feature = "schema")]
+impl<T> JsonSchemaMaybe for T where T: JsonSchema {}

src/interner.rs

@@ -37,6 +37,9 @@ use serde::{
     Serialize,
 };
 
+#[cfg(feature = "schema")]
+use schemars::JsonSchema;
+
 /// A symbol that is not lifetime tracked.
 ///
 /// This can be used by self-referential types but
@@ -74,13 +77,25 @@ impl<T> From<u32> for UntrackedSymbol<T> {
     }
 }
 
+#[cfg(feature = "schema")]
+impl<T> JsonSchema for UntrackedSymbol<T> {
+    fn schema_name() -> String {
+        String::from("UntrackedSymbol")
+    }
+
+    fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
+        gen.subschema_for::<u32>()
+    }
+}
+
 /// A symbol from an interner.
 ///
 /// Can be used to resolve to the associated instance.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 #[cfg_attr(feature = "serde", serde(transparent))]
-pub struct Symbol<'a, T> {
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
+pub struct Symbol<'a, T: 'a> {
     id: u32,
     #[cfg_attr(feature = "serde", serde(skip))]
     marker: PhantomData<fn() -> &'a T>,
@@ -122,6 +137,7 @@ impl<T> Symbol<'_, T> {
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 #[cfg_attr(feature = "serde", serde(transparent))]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub struct Interner<T> {
     /// A mapping from the interned elements to their respective space-efficient
     /// identifiers.

src/lib.rs

@@ -340,9 +340,6 @@ mod registry;
 mod ty;
 mod utils;
 
-#[cfg(test)]
-mod tests;
-
 #[doc(hidden)]
 pub use scale;
 
@@ -395,3 +392,6 @@ where
 {
     MetaType::new::<T>()
 }
+
+#[cfg(test)]
+mod tests;

src/meta_type.rs

@@ -111,3 +111,15 @@ impl MetaType {
         self == &MetaType::new::<crate::impls::PhantomIdentity>()
     }
 }
+
+#[cfg(feature = "schema")]
+impl schemars::JsonSchema for MetaType {
+    fn schema_name() -> String {
+        "MetaType".into()
+    }
+
+    fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
+        // since MetaType does not really get serialized, we don't care about its actual schema
+        gen.subschema_for::<u64>()
+    }
+}

src/portable.rs

@@ -41,6 +41,7 @@ use crate::{
 use scale::Encode;
 
 /// A read-only registry containing types in their portable form for serialization.
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[cfg_attr(feature = "serde", derive(serde::Serialize))]
 #[cfg_attr(all(feature = "serde", feature = "decode"), derive(serde::Deserialize))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
@@ -231,6 +232,7 @@ impl PortableRegistry {
 }
 
 /// Represent a type in it's portable form.
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[cfg_attr(feature = "serde", derive(serde::Serialize))]
 #[cfg_attr(all(feature = "serde", feature = "decode"), derive(serde::Deserialize))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]

src/ty/composite.rs

@@ -69,6 +69,7 @@ use serde::{
 )]
 #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, From, Encode)]
 pub struct TypeDefComposite<T: Form = MetaForm> {
     /// The fields of the composite type.

src/ty/fields.rs

@@ -71,6 +71,7 @@ use serde::{
 )]
 #[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Encode)]
 pub struct Field<T: Form = MetaForm> {
     /// The name of the field. None for unnamed fields.

src/ty/mod.rs

@@ -61,6 +61,7 @@ pub use self::{
 )]
 #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, From, Debug, Encode)]
 pub struct Type<T: Form = MetaForm> {
     /// The unique path to the type. Can be empty for built-in types
@@ -207,6 +208,7 @@ where
     ))
 )]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, From, Debug, Encode)]
 pub struct TypeParameter<T: Form = MetaForm> {
     /// The name of the generic type parameter e.g. "T".
@@ -295,6 +297,7 @@ where
 )]
 #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Encode)]
 pub enum TypeDef<T: Form = MetaForm> {
     /// A composite type (e.g. a struct or a tuple)
@@ -369,6 +372,7 @@ impl IntoPortable for TypeDef {
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Debug)]
 pub enum TypeDefPrimitive {
     /// `bool` type
@@ -421,6 +425,7 @@ pub enum TypeDefPrimitive {
 /// An array type.
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Debug)]
 pub struct TypeDefArray<T: Form = MetaForm> {
     /// The length of the array type.
@@ -481,6 +486,7 @@ where
 )]
 #[cfg_attr(feature = "serde", serde(transparent))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Debug)]
 pub struct TypeDefTuple<T: Form = MetaForm> {
     /// The types of the tuple fields.
@@ -546,6 +552,7 @@ where
 /// A type to refer to a sequence of elements of the same type.
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Debug)]
 pub struct TypeDefSequence<T: Form = MetaForm> {
     /// The element type of the sequence type.
@@ -600,6 +607,7 @@ where
 /// A type wrapped in [`Compact`].
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Debug)]
 pub struct TypeDefCompact<T: Form = MetaForm> {
     /// The type wrapped in [`Compact`], i.e. the `T` in `Compact<T>`.
@@ -644,6 +652,7 @@ where
 /// enabled, but can be decoded or deserialized into the `PortableForm` without this feature.
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Debug)]
 pub struct TypeDefBitSequence<T: Form = MetaForm> {
     /// The type implementing [`bitvec::store::BitStore`].

src/ty/path.rs

@@ -56,6 +56,7 @@ use serde::{
 )]
 #[cfg_attr(feature = "serde", serde(transparent))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Encode)]
 pub struct Path<T: Form = MetaForm> {
     /// The segments of the namespace.

src/ty/variant.rs

@@ -81,6 +81,7 @@ use serde::{
 )]
 #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, From, Encode)]
 pub struct TypeDefVariant<T: Form = MetaForm> {
     /// The variants of a variant type
@@ -154,6 +155,7 @@ where
     ))
 )]
 #[cfg_attr(any(feature = "std", feature = "decode"), derive(scale::Decode))]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Encode)]
 pub struct Variant<T: Form = MetaForm> {
     /// The name of the variant.