---
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
- **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`:

```yaml
dependencies:
  fory: ^0.17.0

dev_dependencies:
  build_runner: ^2.4.0
```

### Basic Example

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

```dart
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:

```bash
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`, `UInt8`, `UInt16`, `UInt32`
- Float wrappers: `Float16`, `Float32`
- Time wrappers: `LocalDate`, `Timestamp`

## Documentation

| Topic                                         | Description                                                     |
| --------------------------------------------- | --------------------------------------------------------------- |
| [Configuration](configuration.md)             | Runtime options, compatible mode, and safety limits             |
| [Basic Serialization](basic-serialization.md) | `serialize`, `deserialize`, generated registration, root graphs |
| [Code Generation](code-generation.md)         | `@ForyStruct`, build runner, and generated namespaces           |
| [Type Registration](type-registration.md)     | ID-based vs name-based registration and registration rules      |
| [Custom Serializers](custom-serializers.md)   | Manual `Serializer<T>` implementations and unions               |
| [Field Configuration](field-configuration.md) | `@ForyField`, field IDs, nullability, references, polymorphism  |
| [Supported Types](supported-types.md)         | Built-in xlang values, wrappers, collections, and structs       |
| [Schema Evolution](schema-evolution.md)       | Compatible structs and evolving schemas                         |
| [Cross-Language](cross-language.md)           | Interoperability rules and field alignment                      |
| [Troubleshooting](troubleshooting.md)         | Common errors, diagnostics, and validation steps                |

## Related Resources

- [Xlang serialization specification](../../specification/xlang_serialization_spec.md)
- [Xlang implementation guide](../../specification/xlang_implementation_guide.md)
- [Cross-language guide](../xlang/index.md)
- [Dart runtime source directory](https://github.com/apache/fory/tree/main/dart)
