This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new c837ee8392 Document how to customize JSON encoding via
`EncoderFactory` (#10741)
c837ee8392 is described below
commit c837ee83926e6c4f327405dcc220de3c7dd06b06
Author: Andrew Lamb <[email protected]>
AuthorDate: Fri Aug 21 09:26:12 2026 -0400
Document how to customize JSON encoding via `EncoderFactory` (#10741)
# Which issue does this PR close?
N/A -- documentation only.
# Rationale for this change
The ability to customize JSON encoding via [`EncoderFactory`] was added
in #7015, but neither the crate-level docs nor the writer module docs
mention it, so users only find the hook by stumbling on
`WriterBuilder::with_encoder_factory`.
[`EncoderFactory`]:
https://docs.rs/arrow-json/latest/arrow_json/trait.EncoderFactory.html
# What changes are included in this PR?
Documentation only, no code changes:
- Crate-level docs: list a custom `EncoderFactory` as an alternative for
binary data encoding
- Misc other wording fixeers
It would be nice to add a matching pointer for customizing *decoding* as
part of #10670
# Are these changes tested?
Covered by existing doc tests and CI rustdoc link checking.
# Are there any user-facing changes?
Documentation only.
---
arrow-json/src/lib.rs | 11 ++++++++---
arrow-json/src/writer/encoder.rs | 11 ++++++++---
arrow-json/src/writer/mod.rs | 8 ++++++++
3 files changed, 24 insertions(+), 6 deletions(-)
diff --git a/arrow-json/src/lib.rs b/arrow-json/src/lib.rs
index 7f0f272b8b..ee5d7df73a 100644
--- a/arrow-json/src/lib.rs
+++ b/arrow-json/src/lib.rs
@@ -20,15 +20,20 @@
//! See the module level documentation for the
//! [`reader`] and [`writer`] for usage examples.
//!
-//! # Binary Data uses `Base16` Encoding
+//! # Binary Data Encoding
//!
//! As per [RFC7159] JSON cannot encode arbitrary binary data. This crate
works around that
//! limitation by encoding/decoding binary data as a [hexadecimal] string (i.e.
//! [`Base16` encoding]).
//!
//! Note that `Base16` only has 50% space efficiency (i.e., the encoded data
is twice as large
-//! as the original). If that is an issue, we recommend to convert binary data
to/from a different
-//! encoding format such as `Base64` instead. See the following example for
details.
+//! as the original). If that is an issue, there are two alternatives:
+//!
+//! 1. Provide a custom encoder. See the [Customizing the encoder] section of
the writer documentation.
+//! 2. Convert binary data to/from a different encoding format such as
`Base64` before
+//! writing / after reading, as shown in the following example.
+//!
+//! [Customizing the encoder]: writer#customizing-the-encoder
//!
//! ## `Base64` Encoding Example
//!
diff --git a/arrow-json/src/writer/encoder.rs b/arrow-json/src/writer/encoder.rs
index 76a1ca440d..50dcceb415 100644
--- a/arrow-json/src/writer/encoder.rs
+++ b/arrow-json/src/writer/encoder.rs
@@ -139,10 +139,15 @@ impl EncoderOptions {
}
}
-/// A trait to create custom encoders for specific data types.
+/// Creates custom encoders for specific data types when writing JSON data.
///
-/// This allows overriding the default encoders for specific data types,
-/// or adding new encoders for custom data types.
+/// This trait allows customizing JSON encoding for specific data types,
+/// or adding new encoders for unsupported or custom data types.
+///
+/// You can register an implementation of this trait using
+/// [`WriterBuilder::with_encoder_factory`].
+///
+/// [`WriterBuilder::with_encoder_factory`]:
crate::writer::WriterBuilder::with_encoder_factory
///
/// # Examples
///
diff --git a/arrow-json/src/writer/mod.rs b/arrow-json/src/writer/mod.rs
index 63ea39dbbb..8f1eefe548 100644
--- a/arrow-json/src/writer/mod.rs
+++ b/arrow-json/src/writer/mod.rs
@@ -104,6 +104,14 @@
//! serde_json::json!({"a": 2}),
//! );
//! ```
+//!
+//! ## Customizing the encoder
+//!
+//! The output produced for each data type can be customized using
+//! [`WriterBuilder::with_encoder_factory`]. For example, you can override the
+//! default hex encoding of binary data to use `Base64` instead, or provide
+//! encoders for types with no built-in encoding, such as unions.
+//! See the example on [`EncoderFactory`].
mod encoder;
use std::{fmt::Debug, io::Write, sync::Arc};
