Variant: Write Variant Values as JSON (#7670)

# Which issue does this PR close?

Closes [Variant: Write Variant Values as
JSON](#7426) #7426
Part of [[EPIC] [Parquet] Implement Variant type support in
Parquet](#6736) #6736

# Rationale for this change
This is an initial version, serving as a simple interface between the
Variant implementation and the Serde JSON library.

A huge thank you to @PinkCrow007, @mprammer, @alamb, the rest of the CMU
variant team, and everyone else we've interacted with who has helped me
get started with contributing to this project. This is my first
Arrow-related PR, and I thank you all for your insight and support.

# What changes are included in this PR?

This PR implements a comprehensive JSON conversion API for Variant types
with three main functions (`variant_to_json`, `variant_to_json_string`,
and `variant_to_json_value`) that convert different Variant types to
JSON format, including primitives, decimals, dates, timestamps, and
binary data with proper escaping and base64 encoding. The implementation
adds missing methods to `VariantObject` and `VariantArray` for
field/element access, includes two new dependencies (`serde_json` and
`base64`), and provides comprehensive test coverage with unit,
integration, and documentation test suites.

Open to input for improving any part of this implementation.

# Are there any user-facing changes?

The new API's added in parquet-variant will be user-facing.

---------

Co-authored-by: Andrew Lamb <[email protected]>

Author: carpecodeum

parquet-variant/Cargo.toml

@@ -35,5 +35,7 @@ rust-version = "1.83"
 [dependencies]
 arrow-schema = { workspace = true }
 chrono = { workspace = true }
+serde_json = "1.0"
+base64 = "0.21"
 
 [lib]

parquet-variant/examples/variant_to_json_examples.rs

@@ -0,0 +1,55 @@
+// 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.
+
+//! Example showing how to convert Variant values to JSON
+
+use parquet_variant::{
+    variant_to_json, variant_to_json_string, variant_to_json_value, VariantBuilder,
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut builder = VariantBuilder::new();
+
+    {
+        let mut person = builder.new_object();
+        person.append_value("name", "Alice");
+        person.append_value("age", 30i32);
+        person.append_value("email", "[email protected]");
+        person.append_value("is_active", true);
+        person.append_value("score", 95.7f64);
+        person.append_value("department", "Engineering");
+        person.finish();
+    }
+
+    let (metadata, value) = builder.finish();
+    let variant = parquet_variant::Variant::try_new(&metadata, &value)?;
+
+    let json_string = variant_to_json_string(&variant)?;
+    let json_value = variant_to_json_value(&variant)?;
+    let pretty_json = serde_json::to_string_pretty(&json_value)?;
+    println!("{}", pretty_json);
+
+    let mut buffer = Vec::new();
+    variant_to_json(&mut buffer, &variant)?;
+    let buffer_result = String::from_utf8(buffer)?;
+
+    // Verify all methods produce the same result
+    assert_eq!(json_string, buffer_result);
+    assert_eq!(json_string, serde_json::to_string(&json_value)?);
+
+    Ok(())
+}

parquet-variant/src/lib.rs

@@ -33,8 +33,10 @@ mod decoder;
 mod variant;
 // TODO: dead code removal
 mod builder;
+mod to_json;
 #[allow(dead_code)]
 mod utils;
 
 pub use builder::*;
+pub use to_json::{variant_to_json, variant_to_json_string, variant_to_json_value};
 pub use variant::*;