Class ScyllaSerializableAttribute

Marks a class or struct as explicitly versioned by the Scylla serialization system, enabling schema migration support and optional type aliasing for polymorphic deserialization.

Inheritance
object
Attribute
ScyllaSerializableAttribute
Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
[AttributeUsage(AttributeTargets.Class|AttributeTargets.Struct, Inherited = false)]
public sealed class ScyllaSerializableAttribute : Attribute
Remarks

Applying this attribute to a type activates the following behaviors in the serialization engine:

  • The current schema version (from Version) is written as a $version property in the serialized output when IncludeVersionInfo is enabled.
  • On deserialization, if the stored $version is lower than the current Version, the engine automatically discovers and chains all ScyllaMigrationAttribute-decorated static methods on the type to upgrade the data to the current schema.
  • The value of TypeAlias is used as the type discriminator key when serializing or deserializing polymorphic object graphs. If TypeAlias is not set, the engine falls back to the type's fully qualified name (FullName).

Types without this attribute can still be serialized and deserialized, but they receive a Version of 0 (treated as unversioned) and their migrations are never triggered. The TypeAlias fallback for unattributed types is also the fully qualified type name.

This attribute is not inherited (Inherited = false). If a derived class introduces new fields that require versioning, it must declare its own [ScyllaSerializable] attribute with an appropriate starting version. 

[ScyllaSerializable(version: 2, TypeAlias = "player")]
public class PlayerData
{
    public string Name { get; set; }
    public int Level { get; set; }

// Populates MaxStamina, which was added in v2.
[ScyllaMigration(1, 2)]
private static PlayerData MigrateV1ToV2(PlayerData old)
{
    old.MaxStamina = 100;
    return old;
}

public int MaxStamina { get; set; }



}

Constructors

ScyllaSerializableAttribute(int)

Initializes a new instance of the ScyllaSerializableAttribute class with the specified schema version.

Declaration
public ScyllaSerializableAttribute(int version = 1)
Parameters
Type Name Description
int version

The current schema version of this type. Must be a positive integer; defaults to 1 for newly created types with no prior migrations. Increment this value each time the type's serialized structure changes (fields added, removed, renamed, or retyped) and add a corresponding ScyllaMigrationAttribute-decorated migration method to handle upgrading older stored data.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if version is less than 1.

Properties

TypeAlias

Gets or sets the short alias used as the $type discriminator in serialized output for polymorphic type identification.

Declaration
public string TypeAlias { get; set; }
Property Value
Type Description
string

A concise string identifier for this type, or null if not specified. When null, the engine uses the type's fully qualified name (FullName) as the discriminator instead.
Remarks

Type aliases serve two purposes:

  • They reduce the size of serialized output compared to writing the full assembly-qualified type name.
  • They provide stability: if a type is renamed or moved to a different namespace, existing serialized data continues to deserialize correctly as long as the alias remains unchanged.

Type aliases must be unique across all types registered with the same serialization engine instance. Aliases are only written to output when IncludeTypeInfo is enabled.

Version

Gets the current schema version of this type.

Declaration
public int Version { get; }
Property Value
Type Description
int

A positive integer (minimum 1) representing the version of the type's serialized structure. The engine compares this value against the $version field stored in serialized data to determine whether any ScyllaMigrationAttribute-decorated migration methods need to run. Version numbers must be monotonically increasing integers starting from 1.

Extension Methods

See Also