Skip to main content
Version: 1.0.0

Schema Evolution

Apache Fory™ supports schema evolution in compatible mode, allowing fields to be added or removed while maintaining compatibility. Xlang mode enables compatible mode by default. In native mode, set compatible=True explicitly when Python-only payloads need schema evolution.

Xlang Default​

import pyfory

f = pyfory.Fory(xlang=True)

Disable Evolution for Stable Classes​

If a dataclass schema is stable and will not change, you can disable evolution for that class to avoid compatible metadata overhead. Use pyfory.dataclass with evolving=False:

import pyfory

@pyfory.dataclass(evolving=False)
class StableMessage:
    id: int
    name: str

pyfory.dataclass also supports slots=True:

@pyfory.dataclass(slots=True)
class SlotMessage:
    id: int

Schema Evolution Example​

import pyfory
from dataclasses import dataclass

# Version 1: Original class
@dataclass
class User:
    name: str
    age: pyfory.Int32

f = pyfory.Fory(xlang=True)
f.register(User, typename="User")
data = f.dumps(User("Alice", 30))

# Version 2: Add new field (backward compatible)
@dataclass
class User:
    name: str
    age: pyfory.Int32
    email: str = "unknown@example.com"  # New field with default

# Can still deserialize old data
user = f.loads(data)
print(user.email)  # "unknown@example.com"

Supported Changes​

  • Add new fields: With default values
  • Remove fields: Old data with extra fields will be skipped
  • Reorder fields: Fields are matched by name, not position

Best Practices​

  1. Always provide default values for new fields
  2. Use typename for cross-language compatibility
  3. Test schema changes before deploying
  4. Document schema versions for your team