Skip to main content
Version: 1.0.0

Xlang Serialization Guide

Apache Fory™ xlang serialization is the default wire format for cross-language payloads. Serialize data in one language and deserialize it in another without manual conversion. You can use direct language model types for small contracts, or use Fory IDL and code generation when a schema-first workflow is a better fit.

Features​

  • No IDL required: Serialize objects directly with language model types.
  • Multi-language support: Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, and Dart interoperate through the same xlang format.
  • Reference support: Shared and circular references work across language boundaries when reference tracking is enabled in each runtime.
  • Schema evolution: Compatible mode is the xlang default so readers can tolerate added, removed, or reordered fields.
  • Out-of-band buffers: Language runtimes can expose zero-copy buffer paths for large binary data.
  • High performance: Runtimes use generated serializers, JIT serializers, or optimized code paths where available.

Supported Languages​

LanguageStatusPackage or target
JavaSupportedorg.apache.fory:fory-core
PythonSupportedpyfory
C++SupportedBazel/CMake build
GoSupportedgithub.com/apache/fory/go/fory
RustSupportedfory crate
JavaScript/TypeScriptSupported@apache-fory/core
C#SupportedApache.Fory
SwiftSupportedSwift Package Manager target
DartSupportedfory package

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 native mode for same-language traffic in Java, Scala, Kotlin, Python, C++, Go, or Rust:

  • All serialization/deserialization happens in the same language
  • You need language-specific features such as Python pickle-style objects or Java serialization hooks
  • You want native-mode schema-consistent payloads for same-language services

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().withXlang(true).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.Int32

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 MappingXlang 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​