---

title: Dart Object Serialization 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.

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.6.1

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

Topic	Description
Configuration	Fory options, compatible mode, and safety limits
Basic Serialization	Default xlang APIs, registration, and interoperability
Code Generation	@ForyStruct, build runner, and generated modules
Struct Inheritance	Superclasses, mixins, private fields, and constructors
External-Type Serialization	Generated serializers for classes owned by another package
Schema Metadata	@ForyField, field IDs, nullability, references, polymorphism
Type Registration	ID-based vs name-based registration and registration rules
Custom Serializers	Custom Serializer<T> implementations and unions
Supported Types	Built-in xlang values, wrappers, collections, and structs
Schema Evolution	Compatible structs and evolving schemas
Web Platform Support	Dart VM/AOT, Flutter, and web support, limits, and validation
gRPC Support	Generated Fory-backed gRPC service companions
Troubleshooting	Common errors, diagnostics, and validation steps

Related Resources

• Xlang serialization specification
• Xlang implementation guide
• Cross-language guide
• Dart implementation source directory

Before decoding bytes from outside the application trust boundary, read Dart Security.