Class ScyllaPropertyAttribute

Specifies custom serialization behavior for an individual field or property, including a custom output name, serialization ordering, and required-value enforcement.

Inheritance
object
Attribute
ScyllaPropertyAttribute
Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
[AttributeUsage(AttributeTargets.Property|AttributeTargets.Field)]
public sealed class ScyllaPropertyAttribute : Attribute
Remarks

All three settings are optional and independent. You may apply this attribute to set only the options you need; unset options fall back to their defaults.

  • Name - overrides the key written to (and read from) the serialized output. Useful for matching external conventions (e.g., snake_case JSON fields) or for shortening keys to reduce payload size.
  • Order - controls the position of this field or property in the serialized output relative to other members of the same type.
  • Required - causes deserialization to throw a SerializationException if the key is absent or its deserialized value is null.

This attribute can be combined with ScyllaIncludeAttribute to customize a non-public member that has been opted into serialization. 

public class PlayerData
{
    [ScyllaProperty(Name = "player_name", Order = 1, Required = true)]
    public string Name { get; set; }

[ScyllaProperty(Name = "hp", Order = 2)]
public int Health { get; set; }

[ScyllaProperty(Order = 3)]
public int Mana { get; set; }



}

Properties

Name

Gets or sets the custom key name to use in the serialized output instead of the actual field or property name as declared in C#.

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

A non-empty string used as the property key during both serialization and deserialization, or null if not set. When null, the engine uses the original member name (the value of MemberName).
Remarks

Custom names are useful for:

  • Maintaining compatibility with external systems or previously serialized data that use a different naming convention.
  • Using shorter keys to reduce serialized payload size.
  • Bridging C# PascalCase or camelCase field names to JSON snake_case keys.

The name is used for both the outgoing key during serialization and the incoming key lookup during deserialization, so changing a custom name is a breaking schema change that requires a migration.

Order

Gets or sets the position of this member in the serialized output relative to other members of the same type. Lower values appear earlier. Defaults to MaxValue.

Declaration
public int Order { get; set; }
Property Value
Type Description
int

Any int value. The engine sorts all serializable members of a type by this value in ascending order, breaking ties alphabetically by member name. Members without an explicit Order receive the default of MaxValue, which places them after all explicitly ordered members and in alphabetical order among themselves.
Remarks

Ordering affects only the written output format (e.g., key order in JSON objects). It has no impact on deserialization correctness, as the engine performs key-based lookup rather than positional parsing.

Required

Gets or sets whether a non-null value for this member is required during deserialization. Defaults to false.

Declaration
public bool Required { get; set; }
Property Value
Type Description
bool

true if the deserialized value must not be null; false to allow missing or null values.
Remarks

When true, the engine validates this member after all properties of the object have been populated. If the member's value is null at that point - either because the key was absent from the serialized data or because its stored value was explicitly null - a SerializationException is thrown. This makes deserialization fail fast rather than silently producing an object in an invalid state.

Note that for value types (int, float, struct, etc.) this check is never triggered because value types cannot be null; the setting is most meaningful for reference-type members.

Extension Methods

See Also