Skip to main content
Version: 1.0.0

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 code that may have a different version of the same model, for example when you deploy services independently and cannot guarantee that both sides update at the same time.

final fory = Fory();

When compatible: true:

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

When compatible: false:

  • Both sides must have exactly the same schema. This is slightly faster and is fine when schemas do not change or all services deploy schema changes at the same time.

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 schema mismatches at runtime.

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);

maxCollectionSize​

Maximum number of elements accepted in any single list, set, or map field. Prevents runaway memory allocation from malformed messages.

final fory = Fory(maxCollectionSize: 100000);

maxBinarySize​

Maximum number of bytes accepted for any single binary blob field.

final fory = Fory(maxBinarySize: 8 * 1024 * 1024);

Defaults​

OptionDefault
compatibletrue
checkStructVersionfalse
maxDepth256
maxCollectionSize1 048 576
maxBinarySize64 MiB

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 namespace + typeName pairs 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 when exact schema matching is required.
  • Set maxDepth, maxCollectionSize, and maxBinarySize to reject unexpectedly large payloads.
  • Prefer generated schemas and explicit field metadata over broad dynamic fields for untrusted input.