postcard_schema_ng/schema/
mod.rs

1//! ## Schema types
2//!
3//! The types in this module are used to define the schema of a given data type.
4//!
5//! The **Postcard Data Model** is nearly identical to the **Serde Data Model**, however Postcard also
6//! allows for one additional type, `Schema`, which maps to the [`DataModelType`] type, allowing
7//! the schema of types to also be sent over the wire and implement the `Schema` trait.
8//!
9//! ## Borrowed vs Owned
10//!
11//! For reasons that have to do with allowing for arbitrarily sized and nested schemas that
12//! can be created at compile/const time, as well as being usable in `no-std` contexts, the
13//! schema types in this module are implemented using a LOT of `&'static` references.
14//!
15//! This is useful in those limited contexts, however it makes it difficult to do things
16//! like deserialize them, as you can't generally get static references at runtime without
17//! a lot of leaking.
18//!
19//! For cases like this, the [`owned`] module exists, which has copies of all of the "borrowed"
20//! versions of the Data Model types. These owned types implement `From` for their borrowed
21//! counterpoint, so if you need to deserialize something, you probably want the Owned variant!
22
23#[cfg(any(feature = "use-std", feature = "alloc"))]
24pub mod owned;
25
26#[cfg(any(feature = "use-std", feature = "alloc"))]
27pub mod fmt;
28
29use serde::Serialize;
30
31/// This enum lists which of the Data Model Types apply to a given type. This describes how the
32/// type is encoded on the wire.
33///
34/// This enum contains all Serde Data Model types as well as a "Schema" Type,
35/// which corresponds to [`DataModelType`] itself.
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
37pub enum DataModelType {
38    /// The `bool` Serde Data Model Type
39    Bool,
40
41    /// The `i8` Serde Data Model Type
42    I8,
43
44    /// The `u8` Serde Data Model Type
45    U8,
46
47    /// A variably encoded i16
48    I16,
49
50    /// A variably encoded i32
51    I32,
52
53    /// A variably encoded i64
54    I64,
55
56    /// A variably encoded i128
57    I128,
58
59    /// A variably encoded u16
60    U16,
61
62    /// A variably encoded u32
63    U32,
64
65    /// A variably encoded u64
66    U64,
67
68    /// A variably encoded u128
69    U128,
70
71    /// A variably encoded usize
72    Usize,
73
74    /// A variably encoded isize
75    Isize,
76
77    /// The `f32` Serde Data Model Type
78    F32,
79
80    /// The `f64` Serde Data Model Type
81    F64,
82
83    /// The `char` Serde Data Model Type
84    Char,
85
86    /// The `String` Serde Data Model Type
87    String,
88
89    /// The `&[u8]` Serde Data Model Type
90    ByteArray,
91
92    /// The `Option<T>` Serde Data Model Type
93    Option(&'static Self),
94
95    /// The `()` Serde Data Model Type
96    Unit,
97
98    /// The "Sequence" Serde Data Model Type
99    Seq(&'static Self),
100
101    /// The "Tuple" Serde Data Model Type
102    Tuple(&'static [&'static Self]),
103
104    /// The "Map" Serde Data Model Type
105    Map {
106        /// The map "Key" type
107        key: &'static Self,
108        /// The map "Value" type
109        val: &'static Self,
110    },
111
112    /// One of the struct Serde Data Model types
113    Struct {
114        /// The name of this struct
115        name: &'static str,
116        /// The data contained in this struct
117        data: Data,
118    },
119
120    /// The "Enum" Serde Data Model Type (which contains any of the "Variant" types)
121    Enum {
122        /// The name of this struct
123        name: &'static str,
124        /// The variants contained in this enum
125        variants: &'static [&'static Variant],
126    },
127
128    /// A [`DataModelType`]/[`OwnedDataModelType`](owned::OwnedDataModelType)
129    Schema,
130}
131
132/// The contents of a struct or enum variant.
133#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
134pub enum Data {
135    /// The "Unit Struct" or "Unit Variant" Serde Data Model Type
136    Unit,
137
138    /// The "Newtype Struct" or "Newtype Variant" Serde Data Model Type
139    Newtype(&'static DataModelType),
140
141    /// The "Tuple Struct" or "Tuple Variant" Serde Data Model Type
142    Tuple(&'static [&'static DataModelType]),
143
144    /// The "Struct" or "Struct Variant" Serde Data Model Type
145    Struct(&'static [&'static NamedField]),
146}
147
148/// This represents a named struct field.
149///
150/// For example, in `struct Ex { a: u32 }` the field `a` would be reflected as
151/// `NamedField { name: "a", ty: DataModelType::U32 }`.
152#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
153pub struct NamedField {
154    /// The name of this field
155    pub name: &'static str,
156    /// The type of this field
157    pub ty: &'static DataModelType,
158}
159
160/// An enum variant e.g. `T::Bar(...)`
161#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
162pub struct Variant {
163    /// The name of this variant
164    pub name: &'static str,
165    /// The data contained in this variant
166    pub data: Data,
167}
postcard_schema_ng/schema/mod.rs

postcard_schema_ng/schema/
mod.rs
