Skip to main content
Version: dev

Field Configuration

This page covers field-level serializer configuration for C# generated serializers.

[ForyObject] and [ForyField]​

Use [ForyObject] to enable source-generated serializers. Use [ForyField] to assign an optional stable non-negative field id or to override the Fory schema type used for a field.

using Apache.Fory;
using S = Apache.Fory.Schema.Types;

[ForyObject]
public sealed class Metrics
{
    [ForyField(Type = typeof(S.UInt32))]
    public uint Count { get; set; }

    [ForyField(Type = typeof(S.Tagged<S.UInt64>))]
    public ulong TraceId { get; set; }

    public long LatencyMicros { get; set; }
}

Id is optional. When it is omitted, compatible mode still matches the field by name.

using Apache.Fory;
using S = Apache.Fory.Schema.Types;

[ForyObject]
public sealed class NestedMetrics
{
    [ForyField(Type = typeof(S.Map<S.Fixed<S.UInt32>, S.List<S.Tagged<S.UInt64>>>))]
    public Dictionary<uint, List<ulong?>?> Values { get; set; } = [];

    [ForyField(3, Type = typeof(S.UInt64))]
    public ulong StableCount { get; set; }
}

Schema Descriptor Types​

Schema descriptors live under Apache.Fory.Schema.Types and are metadata only. They do not replace normal C# carrier types.

Common scalar descriptors include:

  • S.Int32, S.UInt32
  • S.Int64, S.UInt64
  • S.Float16, S.BFloat16, S.Float32, S.Float64

Container descriptors are composable:

  • S.Fixed<TScalar> and S.Tagged<TScalar> for scalar integer encodings
  • S.List<TElement>
  • S.Set<TElement>
  • S.Map<TKey, TValue>
  • S.Array<TElement>

Dense array fields use S.Array<TElement>, for example S.Array<S.Int32> or S.Array<S.BFloat16>.

Nullability comes from the C# carrier type. Use List<ulong?> for nullable list elements and NullableKeyDictionary<TKey, TValue> when a map needs nullable keys.

Nullability and Reference Tracking​

  • Field nullability comes from C# type nullability (string?, nullable value types, etc.).
  • Reference tracking is controlled at runtime by ForyBuilder.TrackRef(...).