| title | Overview |
|---|---|
| sidebar_position | 0 |
| id | index |
| license | 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. |
Fory IDL is a schema definition language for Apache Fory that enables type-safe cross-language serialization. Define your data structures once and generate native data structure code for Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Fory IDL can also describe RPC services; for Java, Python, Go, Rust, C++, C#, Swift, Dart, Scala, Kotlin, and JavaScript, the compiler can generate gRPC service companions that use Fory serialization for request and response payloads.
Fory IDL provides a simple, intuitive syntax for defining cross-language data structures:
package example;
enum Status {
PENDING = 0;
ACTIVE = 1;
COMPLETED = 2;
}
message User {
string name = 1;
int32 age = 2;
optional string email = 3;
list<string> tags = 4;
}
message Item {
string sku = 1;
int32 quantity = 2;
}
message Order {
ref User customer = 1;
list<Item> items = 2;
Status status = 3;
map<string, int32> metadata = 4;
}
message Dog [id=104] {
string name = 1;
int32 bark_volume = 2;
}
message Cat [id=105] {
string name = 1;
int32 lives = 2;
}
union Animal [id=106] {
Dog dog = 1;
Cat cat = 2;
}
message LookupRequest [id=107] {
string name = 1;
}
message LookupResponse [id=108] {
Animal animal = 1;
}
service AnimalService {
rpc Lookup (LookupRequest) returns (LookupResponse);
rpc Classify (Animal) returns (Animal);
}Generate Java, Python, Go, Rust, C++, C#, Swift, Dart, Scala, Kotlin, and JavaScript models plus gRPC service companions with:
foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --cpp_out=./generated/cpp --csharp_out=./generated/csharp --swift_out=./generated/swift --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpcThe generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. See Fory gRPC for language-specific dependencies, server and client setup, streaming modes, browser support, and interoperability boundaries.
Define your data model once in Fory IDL and generate consistent, type-safe code across all languages. This ensures:
- Type Safety: Catch type errors at compile time, not when the code runs
- Consistency: All languages use the same field names, types, and structures
- Documentation: Schema serves as living documentation
- Evolution: Managed schema changes across all implementations
Unlike generic IDLs, Fory IDL is designed specifically for Fory serialization:
- Reference Tracking: First-class support for shared and circular references via
ref - Nullable Fields: Explicit
optionalmodifier for nullable types - Type Registration: Built-in support for both numeric IDs and name-based registration
- Native Code Generation: Generates idiomatic code with Fory annotations/macros
Generated code uses native language constructs:
- Java: Plain POJOs with
@ForyFieldannotations - Python: Dataclasses with type hints
- Go: Structs with struct tags
- Rust: Structs with
#[derive(ForyStruct)] - C++: Structs with
FORY_STRUCTmacros - C#:
[ForyStruct]classes,[ForyEnum]enums,[ForyUnion]unions, and registration helpers - JavaScript/TypeScript: Interfaces with schema module helpers
- Swift: Fory model macros with field/case metadata and registration helpers
- Dart:
@ForyStructclasses with@ForyFieldannotations and registration helpers - Scala: Scala 3
case class, normal class, enum, and ADT enum models with macro-derived serializers - Kotlin: Kotlin
data class, enum, and sealed class models with KSP-generated serializers
pip install fory-compilerOr install from source:
cd compiler
pip install -e .Create example.fdl:
package example;
message Person {
string name = 1;
int32 age = 2;
optional string email = 3;
}# Generate for all languages
foryc example.fdl --output ./generated
# Generate for specific languages
foryc example.fdl --lang java,python,cpp,csharp,javascript,swift,dart,scala,kotlin --output ./generatedJava:
Person person = new Person();
person.setName("Alice");
person.setAge(30);
byte[] data = person.toBytes();Python:
import pyfory
from example import Person
person = Person(name="Alice", age=30)
data = bytes(person) # or `person.to_bytes()`JavaScript/TypeScript:
import { deserializePerson, serializePerson } from "./generated/example";
const data = serializePerson({ name: "Alice", age: 30, email: null });
const person = deserializePerson(data);| Document | Description |
|---|---|
| Fory IDL Syntax | Complete language syntax and grammar |
| Type System | Primitive types, collections, and type rules |
| RPC Services | Service and RPC method syntax |
| Compiler CLI | Compiler commands and options |
| Build Integration | Maven, Gradle, build.rs, CMake, Bazel, and more |
| Generated Code | Output format for each target language |
| Protocol Buffers IDL Support | Protobuf mapping rules and adoption guidance |
| FlatBuffers IDL Support | FlatBuffers mapping rules and codegen differences |
optional: Field can be null/Noneref: Enable reference tracking for shared/circular referenceslist: Field is an ordered collection (alias:repeated)array: Field is dense one-dimensional bool or numeric data
message Example {
optional string nullable = 1;
ref Node parent = 2;
list<int32> numbers = 3;
}Fory IDL types map to native types in each language:
| Fory IDL Type | Java | Python | C++ | Go | Rust | JavaScript/TypeScript | C# | Swift | Dart | Scala | Kotlin |
|---|---|---|---|---|---|---|---|---|---|---|---|
int32 |
int |
pyfory.Int32 |
int32_t |
int32 |
i32 |
number |
int |
Int32 |
int |
Int |
Int |
string |
String |
str |
std::string |
string |
String |
string |
string |
String |
String |
String |
String |
bool |
boolean |
bool |
bool |
bool |
bool |
boolean |
bool |
Bool |
bool |
Boolean |
Boolean |
See Type System for complete mappings.
- Use meaningful package names: Group related types together
- Assign type IDs for performance: Numeric IDs are faster than name-based registration
- Reserve ID ranges: Leave gaps for future additions (e.g., 100-199 for users, 200-299 for orders)
- Use
optionalexplicitly: Make nullability clear in the schema - Use
reffor shared objects: Enable reference tracking when objects are shared
See the examples directory for complete working examples.