Skip to main content

apache_avro/documentation/
avro_data_model_to_serde.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! # Mapping the Avro data model to the Serde data model
19//!
20//! When manually mapping an Avro schema to Rust types it is important to understand
21//! how the different data models are mapped. When mapping from Rust types to an Avro schema,
22//! see [the documentation for the reverse](super::serde_data_model_to_avro).
23//!
24//! Only the mapping as defined here is supported. Any other behavior might change in a minor version.
25//!
26//! ## Primitive Types
27//! - `null`: `()`
28//! - `boolean`: [`bool`]
29//! - `int`: [`i32`] (or [`i16`], [`i8`], [`u16`], [`u8`])
30//! - `long`: [`i64`] (or [`u32`])
31//! - `float`: [`f32`]
32//! - `double`: [`f64`]
33//! - `bytes`: [`Vec<u8>`](std::vec::Vec) (or any type that uses [`Serializer::serialize_bytes`](serde::Serializer), [`Deserializer::deserialize_bytes`](serde::Deserializer), [`Deserializer::deserialize_byte_buf`](serde::Deserializer))
34//!     - It is required to use [`apache_avro::serde::bytes`] as otherwise Serde will (de)serialize a `Vec` as an array of integers instead.
35//! - `string`: [`String`] (or any type that uses [`Serializer::serialize_str`](serde::Serializer), [`Deserializer::deserialize_str`](serde::Deserializer), [`Deserializer::deserialize_string`](serde::Deserializer))
36//!
37//! ## Complex Types
38//! - `records`: A struct with the same name and fields or a tuple with the same fields.
39//!     - Extra fields can be added to the struct if they are marked with `#[serde(skip)]`
40//! - `enums`: A enum with the same name and unit variants for every symbol
41//!     - The index of the symbol must match the index of the variant
42//! - `arrays`: [`Vec`] (or any type that uses [`Serializer::serialize_seq`](serde::Serializer), [`Deserializer::deserialize_seq`](serde::Deserializer))
43//!     - `[T; N]` is (de)serialized as a tuple by Serde, to (de)serialize them as an `array` use [`apache_avro::serde::array`]
44//! - `maps`: [`HashMap<String, _>`](std::collections::HashMap) (or any type that uses [`Serializer::serialize_map`](serde::Serializer), [`Deserializer::deserialize_map`](serde::Deserializer))
45//! - `unions`: An enum with a variant for each union variant
46//!     - The index of the union variant must match the enum variant
47//!     - A `null` can be a unit variant or a newtype variant with a unit type
48//!     - All other variants must be newtype variants, struct variants, or tuple variants.
49//! - `fixed`: [`Vec<u8>`](std::vec::Vec) (or any type that uses [`Serializer::serialize_bytes`](serde::Serializer), [`Deserializer::deserialize_bytes`](serde::Deserializer), [`Deserializer::deserialize_byte_buf`](serde::Deserializer))
50//!     - It is required to use [`apache_avro::serde::fixed`] as otherwise Serde will (de)serialize a `Vec` as an array of integers instead.
51//!
52//! [`apache_avro::serde::array`]: crate::serde::array
53//! [`apache_avro::serde::bytes`]: crate::serde::bytes
54//! [`apache_avro::serde::fixed`]: crate::serde::fixed