Skip to main content
Version: dev

Schema Evolution

Apache Fory™ C# supports schema evolution in Compatible(true) mode.

Compatible Mode​

Fory fory = Fory.Builder()
    .Compatible(true)
    .Build();

Compatible mode writes type metadata that allows readers and writers with different struct definitions to interoperate.

Example: Add a Field​

using Apache.Fory;

[ForyObject]
public sealed class OneStringField
{
    public string? F1 { get; set; }
}

[ForyObject]
public sealed class TwoStringField
{
    public string F1 { get; set; } = string.Empty;
    public string F2 { get; set; } = string.Empty;
}

Fory fory1 = Fory.Builder().Compatible(true).Build();
fory1.Register<OneStringField>(200);

Fory fory2 = Fory.Builder().Compatible(true).Build();
fory2.Register<TwoStringField>(200);

byte[] payload = fory1.Serialize(new OneStringField { F1 = "hello" });
TwoStringField evolved = fory2.Deserialize<TwoStringField>(payload);

// F2 falls back to default value on reader side.
System.Diagnostics.Debug.Assert(evolved.F1 == "hello");
System.Diagnostics.Debug.Assert(evolved.F2 == string.Empty);

Schema-Consistent Mode with Version Check​

If you want strict schema identity checks instead of evolution behavior:

Fory strict = Fory.Builder()
    .Compatible(false)
    .CheckStructVersion(true)
    .Build();

This mode throws on schema hash mismatches.

Best Practices​

  1. Use Compatible(true) for independently deployed services.
  2. Keep stable type IDs across versions.
  3. Add new fields with safe defaults.
  4. Use CheckStructVersion(true) when strict matching is required.