Skip to main content
Version: dev

Cross-Language Serialization Guide

Apache Fory™ xlang (cross-language) serialization enables seamless data exchange between different programming languages. Serialize data in one language and deserialize it in another without manual data conversion. You can use either direct native types (no IDL) or a schema-first Fory IDL workflow.

Features​

  • No IDL Required: Serialize objects directly with native language types
  • Multi-Language Support: Java, Python, C++, Go, Rust, JavaScript all interoperate seamlessly
  • Reference Support: Shared and circular references work across language boundaries
  • Schema Evolution: Forward/backward compatibility when class definitions change
  • Zero-Copy: Out-of-band serialization for large binary data
  • High Performance: JIT compilation and optimized binary protocol

Supported Languages​

LanguageStatusPackage
Java✅org.apache.fory:fory-core
Python✅pyfory
C++✅Bazel/CMake build
Go✅github.com/apache/fory/go/fory
Rust✅fory crate
JavaScript✅@apache-fory/fory

When to Use Xlang Mode​

Use xlang mode when:

  • Building multi-language microservices
  • Creating polyglot data pipelines
  • Sharing data between frontend (JavaScript) and backend (Java/Python/Go)

Use language-native mode when:

  • All serialization/deserialization happens in the same language
  • Maximum performance is required (native mode is faster)
  • You need language-specific features (Python pickle compatibility, Java serialization hooks)

Quick Example​

Java (Producer)​

import org.apache.fory.*;
import org.apache.fory.config.*;

public class Person {
    public String name;
    public int age;
}

Fory fory = Fory.builder()
    .withLanguage(Language.XLANG)
    .build();
fory.register(Person.class, "example.Person");

Person person = new Person();
person.name = "Alice";
person.age = 30;
byte[] bytes = fory.serialize(person);
// Send bytes to Python, Go, Rust, etc.

Python (Consumer)​

import pyfory
from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: pyfory.Int32Type

fory = pyfory.Fory(xlang=True)
fory.register_type(Person, typename="example.Person")

# Receive bytes from Java
person = fory.deserialize(bytes_from_java)
print(f"{person.name}, {person.age}")  # Alice, 30

Fory IDL​

For schema-first projects, Fory also provides Fory IDL and code generation.

  • Compiler docs: Fory IDL Overview
  • Best for large multi-language message contracts and long-lived schemas

Minimal IDL Example​

Create person.fdl:

package example;

message Person {
    string name = 1;
    int32 age = 2;
    optional string email = 3;
}

Generate code:

foryc person.fdl --lang java,python,go,rust,cpp --output ./generated

This generates native language types with consistent field/type mappings across all targets.

When to Fory IDL​

OptionUse WhenWhy
Native xlang types (no IDL)You only have a few message types and want to move quicklyAvoids the integration/setup cost of introducing and operating the compiler
Fory IDL (schema-first + codegen)You have many messages across multiple languages/teams/servicesProvides a single contract, stronger consistency, and easier long-term evolution
Hybrid (start native, move to IDL)Project starts small but message count and cross-team dependency growsLets you keep early velocity, then standardize once schema complexity increases

Documentation​

TopicDescription
Getting StartedInstallation and basic setup for all languages
Type MappingCross-language type mapping reference
SerializationBuilt-in types, custom types, reference handling
Zero-CopyOut-of-band serialization for large data
Row FormatCache-friendly binary format with random access
TroubleshootingCommon issues and solutions

Language-Specific Guides​

For language-specific details and API reference:

Specifications​