docs/guide/dart/index.md

title: Dart Serialization Guide sidebar_position: 0 id: dart_serialization_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, Go, C#, Python, and other Fory-supported languages.

Why Fory Dart?

Cross-language: 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 at runtime
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 manual serializer for any type that cannot be annotated

Quick Start

Requirements

Dart SDK 3.6 or later
build_runner (generates the serializer code)

Install

Add the dependency to your pubspec.yaml:

dependencies:
  fory: ^0.17.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 = '';
  Int32 age = Int32(0);
  Color favoriteColor = Color.red;
  List<String> tags = <String>[];
}

void main() {
  final fory = Fory();
  PersonFory.register(
    fory,
    Color,
    namespace: 'example',
    typeName: 'Color',
  );
  PersonFory.register(
    fory,
    Person,
    namespace: 'example',
    typeName: 'Person',
  );

  final person = Person()
    ..name = 'Ada'
    ..age = Int32(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 --delete-conflicting-outputs

PersonFory is generated by build_runner. The namespace and typeName values are how peers in other languages identify the same type — keep them stable once your service is in production.

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
@ForyField(...) — per-field options (skip, ID, nullability, references)
Integer wrappers: Int8, Int16, Int32, Int64, Uint8, Uint16, Uint32, Uint64
Float wrappers: Float16, Bfloat16, Float32
16-bit float arrays: Float16List, Bfloat16List
Time types: LocalDate, Timestamp, Duration

Documentation

Topic	Description
Configuration	Runtime options, compatible mode, and safety limits
Basic Serialization	`serialize`, `deserialize`, generated registration, root graphs
Code Generation	`@ForyStruct`, build runner, and generated namespaces
Type Registration	ID-based vs name-based registration and registration rules
Custom Serializers	Manual `Serializer<T>` implementations and unions
Field Configuration	`@ForyField`, field IDs, nullability, references, polymorphism
Supported Types	Built-in xlang values, wrappers, collections, and structs
Schema Evolution	Compatible structs and evolving schemas
Cross-Language	Interoperability rules and field alignment
Web Platform Support	Dart VM/AOT, Flutter, and web support, limits, and validation
Troubleshooting	Common errors, diagnostics, and validation steps