postcard_schema/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 [`NamedValue`] 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/// A "NamedType" is used to describe the schema of a given type.
32///
33/// It contains two pieces of information:
34///
35/// * A `name`, which is the name of the type, e.g. "u8" for [`u8`].
36/// * A `ty`, which is one of the possible [`DataModelType`]s any given type can be represented as.
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
38pub struct NamedType {
39    /// The name of this type
40    pub name: &'static str,
41    /// The type
42    pub ty: &'static DataModelType,
43}
44
45/// This enum lists which of the Data Model Types apply to a given type. This describes how the
46/// type is encoded on the wire.
47///
48/// This enum contains all Serde Data Model types other than enum variants which exist in
49/// [`DataModelVariant`], as well as a "Schema" Model Type, which maps to [`NamedType`].
50#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
51pub enum DataModelType {
52    /// The `bool` Serde Data Model Type
53    Bool,
54
55    /// The `i8` Serde Data Model Type
56    I8,
57
58    /// The `u8` Serde Data Model Type
59    U8,
60
61    /// A variably encoded i16
62    I16,
63
64    /// A variably encoded i32
65    I32,
66
67    /// A variably encoded i64
68    I64,
69
70    /// A variably encoded i128
71    I128,
72
73    /// A variably encoded u16
74    U16,
75
76    /// A variably encoded u32
77    U32,
78
79    /// A variably encoded u64
80    U64,
81
82    /// A variably encoded u128
83    U128,
84
85    /// A variably encoded usize
86    Usize,
87
88    /// A variably encoded isize
89    Isize,
90
91    /// The `f32` Serde Data Model Type
92    F32,
93
94    /// The `f64 Serde Data Model Type
95    F64,
96
97    /// The `char` Serde Data Model Type
98    Char,
99
100    /// The `String` Serde Data Model Type
101    String,
102
103    /// The `&[u8]` Serde Data Model Type
104    ByteArray,
105
106    /// The `Option<T>` Serde Data Model Type
107    Option(&'static NamedType),
108
109    /// The `()` Serde Data Model Type
110    Unit,
111
112    /// The "unit struct" Serde Data Model Type
113    UnitStruct,
114
115    /// The "newtype struct" Serde Data Model Type
116    NewtypeStruct(&'static NamedType),
117
118    /// The "Sequence" Serde Data Model Type
119    Seq(&'static NamedType),
120
121    /// The "Tuple" Serde Data Model Type
122    Tuple(&'static [&'static NamedType]),
123
124    /// The "Tuple Struct" Serde Data Model Type
125    TupleStruct(&'static [&'static NamedType]),
126
127    /// The "Map" Serde Data Model Type
128    Map {
129        /// The map "Key" type
130        key: &'static NamedType,
131        /// The map "Value" type
132        val: &'static NamedType,
133    },
134
135    /// The "Struct" Serde Data Model Type
136    Struct(&'static [&'static NamedValue]),
137
138    /// The "Enum" Serde Data Model Type (which contains any of the "Variant" types)
139    Enum(&'static [&'static NamedVariant]),
140
141    /// A NamedType/OwnedNamedType
142    Schema,
143}
144
145/// This is similar to [`DataModelType`], however it only contains the potential Data Model Types
146/// used as variants of an `enum`.
147#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
148pub enum DataModelVariant {
149    /// The "unit variant" Serde Data Model Type
150    UnitVariant,
151    /// The "newtype variant" Serde Data Model Type
152    NewtypeVariant(&'static NamedType),
153    /// The "Tuple Variant" Serde Data Model Type
154    TupleVariant(&'static [&'static NamedType]),
155    /// The "Struct Variant" Serde Data Model Type
156    StructVariant(&'static [&'static NamedValue]),
157}
158
159/// This represents a named struct field.
160///
161/// For example, in `struct Ex { a: u32 }` the field `a` would be reflected as
162/// `NamedValue { name: "a", ty: DataModelType::U32 }`.
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
164pub struct NamedValue {
165    /// The name of this value
166    pub name: &'static str,
167    /// The type of this value
168    pub ty: &'static NamedType,
169}
170
171/// An enum variant with a name, e.g. `T::Bar(...)`
172#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
173pub struct NamedVariant {
174    /// The name of this variant
175    pub name: &'static str,
176    /// The type of this variant
177    pub ty: &'static DataModelVariant,
178}
postcard_schema/schema/mod.rs

postcard_schema/schema/
mod.rs
