VYaml Documentation

VYaml is a high-performance, low-allocation YAML 1.2 implementation for .NET and Unity. It is designed to handle UTF-8 byte sequences directly to minimize memory footprint.

Key Capabilities:

• YAML Parser (Reader): Supports YAML 1.2 and Unity's non-standard serialized YAML format (which may include a "stripped" symbol in the document start line).
• YAML Emitter (Writer): Supports primitive types, various scalar styles (plain, double-quoted, literal), and multiple sequence/mapping styles (block, flow).
• Serialization/Deserialization:
  • Converts between YAML and C# user-defined types.
  • Supports dynamic for primitive collections.
  • Supports interface-typed and abstract class-typed objects.
  • Supports YAML anchors (&) and aliases (*).
  • Supports deserializing multiple YAML documents into a C# collection.
• Customization: Allows renaming keys and ignoring members during serialization.

You can customize how specific C# types are serialized or deserialized by implementing IYamlFormatter<T>. To integrate these custom formatters into the YamlSerializer, use YamlSerializerOptions with a CompositeResolver.

It is recommended to include StandardResolver.Instance at the end of your resolver list to ensure default behavior remains available for types you haven't explicitly customized.

var options = new YamlSerializerOptions
{
    Resolver = CompositeResolver.Create(
        new IYamlFormatter[]
        {
            new YourCustomFormatter1(), // Your custom formatter
        },
        new IYamlFormatterResolver[]
        {
            new YourCustomResolver(),  // Your custom resolver
            StandardResolver.Instance, // Fallback to default behavior
        })
};

YamlSerializer.Deserialize<T>(yaml, options);
YamlSerializer.Serialize(obj, options);

VYaml supports deserializing interface-typed or abstract-class-typed objects using a feature called Union. This allows you to use YAML tags (e.g., !foo) to identify which concrete type to instantiate.

1. Annotate the interface or abstract class with [YamlObjectUnion("tag", typeof(ConcreteType))] for each possible implementation.
2. Annotate the interface/abstract class itself with [YamlObject].
3. Ensure all concrete types are also annotated with [YamlObject].
4. Each union tag must be unique.

[YamlObject]
[YamlObjectUnion("!foo", typeof(FooClass))]
[YamlObjectUnion("!bar", typeof(BarClass))]
public partial interface IUnionSample
{
}

[YamlObject]
public partial class FooClass : IUnionSample
{
    public int A { get; set; }
}

[YamlObject]
public partial class BarClass : IUnionSample
{
    public string? B { get; set; }
}

// Deserializing a tagged document
var obj = YamlSerializer.Deserialize<IUnionSample>(UTF8.GetBytes("!foo { a: 100 }"));
// obj is now an instance of FooClass

To use VYaml for serialization, define a struct or class and annotate it with the [YamlObject] attribute. The class must be marked as partial because VYaml uses Source Generators to create the necessary metaprogramming code.

Serialization

• YamlSerializer.Serialize<T>(obj): Returns a UTF-8 byte array (recommended for files/data stores).
• YamlSerializer.SerializeToString(obj): Returns a C# string (involcur UTF-16 conversion overhead).

Deserialization

• await YamlSerializer.DeserializeAsync<T>(stream): Deserializes from a stream asynchronously.
• YamlSerializer.Deserialize<T>(utf8Bytes): Deserializes from a UTF-8 byte array.
• YamlSerializer.Deserialize<dynamic>(utf8Bytes): Deserializes into a dynamic object for schema-less access.

Ignoring Members

Use the [YamlIgnore] attribute to prevent a public member from being serialized.

using VYaml.Annotations;

[YamlObject]
public partial class Sample
{
    public string A;
    public string B { get; set; }

    [YamlIgnore]
    public int PublicProperty2 => PublicProperty + PublicField;
}

// Usage
var utf8Yaml = YamlSerializer.Serialize(new Sample { A = "hello", B = "foo" });
var sample = await YamlSerializer.DeserializeAsync<Sample>(stream);

By default, VYaml maps C# property names to YAML keys using lowerCamelCase. You can customize this globally via YamlSerializerOptions or per-type/per-member using attributes.

Global Configuration

Set YamlSerializerOptions.NamingConvention to one of the following:

• NamingConvention.LowerCamelCase (Default)
• NamingConvention.UpperCamelCase (e.g., PropertyName)
• NamingConvention.SnakeCase (e.g., property_name)
• NamingConvention.KebabCase (e.g., property-name)

Note: Using a global convention other than the default may cause a slight runtime performance degradation.

Per-Type and Per-Member Customization

To avoid performance degradation, use attributes directly on your classes or members:

• [YamlObject(NamingConvention.SnakeCase)]: Sets the convention for the entire class.
• [YamlMember("alias-name")]: Sets a specific key name for a single member.

// Global
var options = YamlSerializerOptions.Standard;
options.NamingConvention = NamingConvention.SnakeCase;
YamlSerializer.Serialize(new A { FooBar = 123 }, options); // { foo_bar: 123 }

// Per-type (No performance penalty)
[YamlObject(NamingConvention.SnakeCase)]
public partial class Sample
{
    public int FooBar { get; init; }
}

// Per-member
[YamlObject]
public partial class Sample
{
    [YamlMember("foo-bar-alias")]
    public int FooBar { get; init; }
}

You can create complex, nested YAML structures by nesting BeginMapping and BeginSequence calls within the Utf8YamlEmitter.

emitter.BeginSequence();
{
    // Flow style sequence: [100, "&hoge", bra]
    emitter.BeginSequence(SequenceStyle.Flow);
    {
        emitter.WriteInt32(100);
        emitter.WriteString("&hoge");
        emitter.WriteString("bra");
    }
    emitter.EndSequence();

    // Block style mapping with nested sequence
    emitter.BeginMapping();
    {
        emitter.WriteString("key1");
        emitter.WriteString("item1");

        emitter.WriteString("key2");
        emitter.BeginSequence();
        {
            emitter.WriteString("nested-item1");
            emitter.WriteString("nested-item2");
            emitter.BeginMapping();
            {
                emitter.WriteString("nested-key1");
                emitter.WriteInt32(100);
            }
            emitter.EndMapping();
        }
        emitter.EndSequence();
    }
    emitter.EndMapping();
}
emitter.EndSequence();