Skip to main content
Version: 1.2

Configuration

This page explains the Fory constructor options.

Creating a Fory Instance​

Pass options directly to the constructor:

import 'package:fory/fory.dart';

// defaults: xlang wire format with compatible schema evolution
final fory = Fory();

// customize limits while keeping default compatible mode
final fory = Fory(
  maxDepth: 512,
);

Create one instance per application and reuse it; there is no benefit to creating a new Fory per request.

Options​

compatible​

Compatible mode is enabled by default. Keep it enabled when your service needs to handle payloads from different versions of the same model, for example during rolling deployments or client/server version skew.

When compatible: true:

  • Adding or removing fields on one side does not break the other.
  • Peers must still use the same name (or numeric id) to identify types.

When compatible: false:

  • Both sides must have exactly the same schema. Use this only when every reader and writer always uses that schema and you want faster serialization and smaller size. For cross-language payloads, set compatible: false only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL.
final fory = Fory(compatible: false);

checkStructVersion​

Relevant only when compatible: false. When true, Fory validates that the schema version in the payload matches the one the receiver knows about, catching accidental mismatches for intentional same-schema payloads.

final fory = Fory(
  compatible: false,
  checkStructVersion: true, // default
);

This option has no effect when compatible: true.

maxDepth​

Limits how deeply nested an object graph can be. Increase this if you have legitimately deep trees; lower it to reject unexpectedly deep payloads fast.

final fory = Fory(maxDepth: 128);

Defaults​

OptionDefault
compatibletrue
checkStructVersionfalse
maxDepth256

Xlang Notes​

When Fory is used to communicate between services written in different languages:

  • Keep compatible mode enabled on all sides if any side needs schema evolution.
  • Use the same numeric IDs or name values on every side.
  • Match the compatible setting on both the writing and reading side — mismatching modes will fail.

Security​

Security-related configuration:

  • Register only the expected generated models before deserializing untrusted payloads.
  • Use checkStructVersion: true with compatible: false for intentional same-schema payloads.
  • Set maxDepth to reject unexpectedly deep payload shapes.
  • Prefer generated schemas and explicit field metadata over broad dynamic fields for untrusted input.