This is an automated email from the ASF dual-hosted git repository. kriskras99 pushed a commit to branch feat/enums in repository https://gitbox.apache.org/repos/asf/avro-rs.git
commit e742a565a22429a43be60500b25d72caa23f4a69 Author: default <[email protected]> AuthorDate: Tue Mar 10 15:03:45 2026 +0000 start on docs --- avro/src/documentation/serde_datamodel_to_avro.rs | 63 +++++++++++++++++++++++ avro/src/serde/derive.rs | 37 ++----------- avro/src/serde/with.rs | 8 +-- avro_derive/tests/derive.rs | 2 + 4 files changed, 73 insertions(+), 37 deletions(-) diff --git a/avro/src/documentation/serde_datamodel_to_avro.rs b/avro/src/documentation/serde_datamodel_to_avro.rs new file mode 100644 index 0000000..5e1ad7f --- /dev/null +++ b/avro/src/documentation/serde_datamodel_to_avro.rs @@ -0,0 +1,63 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! # Mapping the Serde datamodel to the Avro datamodel +//! +//! When manually mapping Rust types to a Avro schema, or the reverse, it is important to understand +//! how the datamodels are mapped. This should only be done in very specific circumstances, most users +//! should use the [`AvroSchema`] derive macro. +//! +//! Only the schemas as generated by the [`AvroSchema`] derive macro and the mapping as defined here are +//! supported. Any other behaviour is not supported. +//! +//! ## Primitive types +//! - `bool` -> [`Schema::Boolean`] +//! - `i8`, `i16`, `i32`, `u8`, `u16` -> [`Schema::Int`] +//! - `i64`, `u32` -> [`Schema::Long`] +//! - `u64` -> [`Schema::Fixed`]`(name: "u64", size: 8)` +//! - This is not a `Schema::Long` as that is a signed number of maximum 64 bits. +//! - `i128` -> [`Schema::Fixed`]`(name: "i128", size: 16)` +//! - `u128` -> [`Schema::Fixed`]`(name: "u128", size: 16)` +//! - `f32` -> [`Schema::Float`] +//! - `f64` -> [`Schema::Double`] +//! - `char` -> [`Schema::String`] +//! - Only one character allowed, deserializer will return an error for strings with more than one character. +//! - `tuple` -> [`Schema::Record`] with a field for every tuple index +//! - `[T; N]` -> [`Schema::Record`] with a field for every array index +//! - To (de)serialize as a [`Schema::Array`] use [`apache_avro::serde::array`] +//! - To (de)serialize as a [`Schema::Fixed`] use [`apache_avro::serde::fixed`] +//! - To (de)serialize as a [`Schema::Bytes`] use [`apache_avro::serde::bytes`] +//! +//! ## Standard library types +//! - `string` -> [`Schema::String`] +//! - `` +//! +//! +//! [`apache_avro::serde::array`]: crate::serde::array +//! [`apache_avro::serde::bytes`]: crate::serde::bytes +//! [`apache_avro::serde::fixed`]: crate::serde::fixed +//! [`AvroSchema`]: crate::AvroSchema +//! [`Schema::Array`]: crate::schema::Schema::Array +//! [`Schema::Boolean`]: crate::schema::Schema::Boolean +//! [`Schema::Bytes`]: crate::schema::Schema::Bytes +//! [`Schema::Double`]: crate::schema::Schema::Double +//! [`Schema::Fixed`]: crate::schema::Schema::Fixed +//! [`Schema::Float`]: crate::schema::Schema::Float +//! [`Schema::Int`]: crate::schema::Schema::Int +//! [`Schema::Long`]: crate::schema::Schema::Long +//! [`Schema::Record`]: crate::schema::Schema::Record +//! [`Schema::String`]: crate::schema::Schema::String \ No newline at end of file diff --git a/avro/src/serde/derive.rs b/avro/src/serde/derive.rs index a65dd9a..68653bf 100644 --- a/avro/src/serde/derive.rs +++ b/avro/src/serde/derive.rs @@ -17,7 +17,7 @@ use crate::Schema; use crate::schema::{ - FixedSchema, Name, NamespaceRef, RecordField, RecordSchema, UnionSchema, UuidSchema, + FixedSchema, Name, NamespaceRef, RecordField, RecordSchema, UnionSchema, UuidSchema }; use std::borrow::Cow; use std::collections::{HashMap, HashSet}; @@ -558,27 +558,6 @@ macro_rules! impl_array_schema ( impl_array_schema!([T] where T: AvroSchemaComponent); impl_array_schema!(Vec<T> where T: AvroSchemaComponent); -// This doesn't work as the macro doesn't allow specifying the N parameter -// impl_array_schema!([T; N] where T: AvroSchemaComponent); - -impl<const N: usize, T> AvroSchemaComponent for [T; N] -where - T: AvroSchemaComponent, -{ - fn get_schema_in_ctxt( - named_schemas: &mut HashSet<Name>, - enclosing_namespace: NamespaceRef, - ) -> Schema { - Schema::array(T::get_schema_in_ctxt(named_schemas, enclosing_namespace)).build() - } - - fn get_record_fields_in_ctxt( - _: &mut HashSet<Name>, - _: NamespaceRef, - ) -> Option<Vec<RecordField>> { - None - } -} impl<T> AvroSchemaComponent for HashMap<String, T> where @@ -825,21 +804,13 @@ mod tests { } #[test] - fn avro_rs_401_array() -> TestResult { - let schema = <[u8; 55]>::get_schema(); - assert_eq!(schema, Schema::array(Schema::Int).build()); - - Ok(()) - } - - #[test] - fn avro_rs_401_option_ref_slice_array() -> TestResult { - let schema = <Option<&[[u8; 55]]>>::get_schema(); + fn avro_rs_401_option_ref_slice() -> TestResult { + let schema = <Option<&[u8]>>::get_schema(); assert_eq!( schema, Schema::union(vec![ Schema::Null, - Schema::array(Schema::array(Schema::Int).build()).build() + Schema::array(Schema::Int).build() ])? ); diff --git a/avro/src/serde/with.rs b/avro/src/serde/with.rs index ead124d..76e7695 100644 --- a/avro/src/serde/with.rs +++ b/avro/src/serde/with.rs @@ -261,7 +261,6 @@ pub mod fixed { /// Returns `None` pub fn get_record_fields_in_ctxt( - _: usize, _: &mut HashSet<Name>, _: NamespaceRef, ) -> Option<Vec<RecordField>> { @@ -524,7 +523,7 @@ pub mod slice_opt { /// } /// ``` /// -/// [`BigDecimal`]: bigdecimal::BigDecimal +/// [`BigDecimal`]: ::bigdecimal::BigDecimal /// [`apache_avro::serde::bigdecimal_opt`]: bigdecimal_opt pub mod bigdecimal { use std::collections::HashSet; @@ -595,7 +594,7 @@ pub mod bigdecimal { /// } /// ``` /// -/// [`BigDecimal`]: bigdecimal::BigDecimal +/// [`BigDecimal`]: ::bigdecimal::BigDecimal /// [`apache_avro::serde::bigdecimal`]: bigdecimal pub mod bigdecimal_opt { use bigdecimal::BigDecimal; @@ -675,6 +674,7 @@ pub mod bigdecimal_opt { /// ``` /// /// [`apache_avro::serde::array_opt`]: array_opt +/// [`Schema::Array`]: crate::schema::Schema::Array pub mod array { use crate::{ AvroSchema, AvroSchemaComponent, Schema, @@ -744,7 +744,7 @@ pub mod array { /// } /// ``` /// -/// [`apache_avro::serde::array`]: array +/// [`apache_avro::serde::array`]: mod@array pub mod array_opt { use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error as _}; use std::collections::HashSet; diff --git a/avro_derive/tests/derive.rs b/avro_derive/tests/derive.rs index 74428b6..1e261bd 100644 --- a/avro_derive/tests/derive.rs +++ b/avro_derive/tests/derive.rs @@ -2521,10 +2521,12 @@ fn avro_rs_476_field_default_provided() { #[avro(default = "[true, false, true]")] _o: Vec<bool>, #[avro(default = "[1,2,3,4,5]")] + #[serde(with = "apache_avro::serde::array")] _p: [u8; 5], #[avro( default = r#"[{"_field": true},{"_field": false},{"_field": true},{"_field": false},{"_field": true}]"# )] + #[serde(with = "apache_avro::serde::array")] _p_alt: [Spam; 5], #[avro(default = r#"{"A": "B"}"#)] _q: HashMap<String, String>,
