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 written as the $type marker of the type and resolved back to the type on load, which is how polymorphic object graphs identify the concrete type. If TypeAlias is not set, the marker is the assembly-qualified type name instead.

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. Their $type marker is the assembly-qualified type name.

The attribute also opts a type in as a target of $type markers where the declared type is object or an interface. On deserialization, such a marker may only resolve to a type annotated with this attribute (any version or alias), a type registered through RegisterAlias(string, Type), or a type handled by a dedicated serializer. Any other type is rejected with a SerializationException, so a hand-edited document cannot instantiate arbitrary types. Mark every type that is stored behind an object or interface field with this attribute.

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 writes the type's assembly-qualified name as the $type marker instead. The FullName default is only an internal index key and is never written.
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 loaded types; a duplicate logs a warning and the first registration wins. An alias is written as the $type marker whenever a marker is written: for every object when IncludeTypeInfo is enabled, and always for a value whose runtime type differs from its declared type. On load, an alias that has not been registered yet is found by a one-time scan of the loaded assemblies. Under IL2CPP, keep the type from being stripped with a [Preserve] attribute or register the alias with RegisterAlias(string, Type).

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