Skip to main content
Version: dev

Dart Object Serialization

Apache Fory™ Dart lets you serialize Dart objects to bytes and deserialize them back, including across services written in Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Scala, Kotlin, and other Fory-supported languages.

Why Fory Dart?​

  • Xlang: serialize in Dart, deserialize in Java, Go, C#, and more without writing any glue code
  • Platform support: use the same generated-serializer API on Dart VM/AOT, Flutter, and web
  • Fast: generated serializer code replaces reflection during serialization
  • Inheritance: ordinary structs flatten concrete superclass and mixin storage into one schema
  • Schema evolution: add or remove fields without breaking existing messages
  • Circular references: optional reference tracking handles shared or recursive object graphs
  • Escape hatch: write a custom serializer for any type that cannot be annotated

Quick Start​

Requirements​

  • Dart SDK 3.7 or later
  • build_runner (generates the serializer code)

Install​

Add the dependency to your pubspec.yaml:

dependencies:
  fory: ^1.5.0

dev_dependencies:
  build_runner: ^2.4.0

Basic Example​

Define your model, run the generator once, then serialize:

import 'package:fory/fory.dart';

part 'person.fory.dart';

enum Color {
  red,
  blue,
}

@ForyStruct()
class Person {
  Person();

  String name = '';

  @ForyField(type: Int32Type())
  int age = 0;
  Color favoriteColor = Color.red;
  List<String> tags = <String>[];
}

void main() {
  final fory = Fory();
  PersonForyModule.register(
    fory,
    Color,
    name: 'example.Color',
  );
  PersonForyModule.register(
    fory,
    Person,
    name: 'example.Person',
  );

  final person = Person()
    ..name = 'Ada'
    ..age = 36
    ..favoriteColor = Color.blue
    ..tags = <String>['engineer', 'mathematician'];

  final bytes = fory.serialize(person);
  final roundTrip = fory.deserialize<Person>(bytes);
  print(roundTrip.name);
}

Generate the companion file before running the program:

dart run build_runner build

PersonForyModule is generated by build_runner. The name value is how peers in other languages identify the same type; keep it stable once your service is in production. Use . inside name to add a namespace prefix.

An ordinary annotated class includes its concrete superclass and applied-mixin storage. Public and same-library private inherited fields need no parent annotation. See Struct Inheritance for private fields, constructors, mixins, and field inclusion options.

API Overview​

  • Fory(...) — create a serializer instance; create once and reuse it
  • fory.serialize(value) — returns Uint8List bytes
  • fory.deserialize<T>(bytes) — returns a T
  • @ForyStruct() — marks a class for code generation
  • @ForyStruct(exposePrivateFields: true) — lets another library's generated child serializer access private state owned by this library
  • @ForyStruct(ignoreInheritedPrivateFields: true) — omits all private superclass and applied-mixin storage from this concrete child's schema
  • @ForyStruct(target: Type) — generates an external structural serializer
  • @ForyField(...) — per-field options and canonical type: overrides
  • @ListField(...), @SetField(...), @MapField(...) — container sugar for nested type: trees
  • Exact-value wrappers: Int64, Uint64, Float32
  • Reduced-precision scalar fields: double with Float16Type or Bfloat16Type
  • 16-bit float arrays: Float16List, Bfloat16List
  • Time types: LocalDate, Timestamp, Duration

Documentation​

TopicDescription
ConfigurationFory options, compatible mode, and safety limits
Basic Serializationserialize, deserialize, generated registration, root graphs
Code Generation@ForyStruct, build runner, and generated modules
Struct InheritanceSuperclasses, mixins, private fields, and constructors
External-Type SerializationGenerated serializers for classes owned by another package
Xlang SerializationInteroperability rules and field alignment
Schema Metadata@ForyField, field IDs, nullability, references, polymorphism
Type RegistrationID-based vs name-based registration and registration rules
Custom SerializersCustom Serializer<T> implementations and unions
Supported TypesBuilt-in xlang values, wrappers, collections, and structs
Schema EvolutionCompatible structs and evolving schemas
Web Platform SupportDart VM/AOT, Flutter, and web support, limits, and validation
gRPC SupportGenerated Fory-backed gRPC service companions
TroubleshootingCommon errors, diagnostics, and validation steps