YamlDotNet.System.Text.Json 1.11.0

YamlDotNet.System.Text.Json

What is this?

This project contains components which allow YamlDotNet to handle System.Text.Json objects and serialize them to YAML and back.

Supported Objects:

• System.Text.Json.Nodes.JsonNode

• System.Text.Json.Nodes.JsonArray

• System.Text.Json.Nodes.JsonObject

• System.Text.Json.Nodes.JsonValue

• System.Text.Json.JsonElement

• System.Text.Json.JsonDocument

• System.Text.Json.Serialization.JsonIgnoreAttribute

  • Conditions - controls whether a property is included while serializing and deserializing
    • Always = Ignore during serialization and deserialization (default)
    • Never = Include during serialization and deserialization
    • WhenWritingNull = Ignore during serialization when the value is null
    • WhenWritingDefault = Ignore during serialization when the value is the type's default value
    • WhenWriting = Ignore during serialization
    • WhenReading = Ignore during deserialization

  Conditional WhenWritingNull and WhenWritingDefault properties remain readable during deserialization. Properties ignored with Always or WhenReading are treated as known ignored properties and skipped when they appear in YAML input.

• System.Text.Json.Serialization.JsonPropertyNameAttribute

  • Name - Specifies the property name that is present in the JSON/YAML when serializing and deserializing.

• System.Text.Json.Serialization.JsonPropertyOrderAttribute

  • Order - Sets the serialization order of the property.

• System.Text.Json.Serialization.JsonStringEnumMemberNameAttribute

  • Name - Sets the value for the Enum Member that is present in the JSON/YAML when serializing and deserializing.

• System.Text.Json.Serialization.JsonExtensionDataAttribute

Installation

dotnet add package YamlDotNet.System.Text.Json

YamlConverter

YamlConverter - exposes Serialize() and Deserialize<T>() methods

// to serialize a object to yaml
var yaml = YamlConverter.Serialize(someObject);

// to serialize json to yaml
var yaml = YamlConverter.SerializeJson(someJson);

// to load your object as a typed object
var obj = YamlConverter.Deserialize<MyTypedObject>(yaml);

How to integrate with YamlDotNet

Example:

using YamlDotNet.Serialization;
using YamlDotNet.System.Text.Json;

var serializer = new SerializerBuilder()
            .AddSystemTextJson()
            .Build();

var yaml = serializer.Serialize(obj);

var deserializer = new DeserializerBuilder()
            .AddSystemTextJson()
            .Build();

var myObject = deserializer.Deserialize<MyType>(yaml)

Trimming

The library is trim-analyzed. Its default YamlConverter methods and AddSystemTextJson extensions for YamlDotNet's reflection based builders are marked as requiring unreferenced code. For trimmed applications, use the YamlConverter overloads that accept a generated StaticContext, or YamlDotNet's static builders.

Add the Vecc.YamlDotNet.Analyzers.StaticGenerator package to the consuming application, declare a partial StaticContext with [YamlStaticContext] and [YamlSerializable(typeof(MyModel))], then pass that context to YamlConverter.Serialize and YamlConverter.Deserialize<T>. Register all application model types used by the context, including enum types. The AddSystemTextJson builder extensions also support YamlDotNet's static builder types.

The samples project demonstrates static-context serialization and deserialization, JSON property attributes, extension data, ordering and default-value options, unmatched-property handling, and direct static-builder configuration. It also runs as the trimmed consumer smoke test in CI.

For applications configuring YamlDotNet's static builders directly, register each model type and enum in the generated static context. The context must include public model properties, fields, and constructors, and enum public fields for JsonStringEnumMemberNameAttribute. For IDictionary<string, JsonElement> extension data, values may be JSON scalars, dictionaries with string keys, sequences, or existing JsonElement, JsonDocument, or JsonNode instances. Arbitrary CLR objects require runtime JSON metadata and are rejected. IDictionary<string, object> extension data retains its values as objects.

Extension-data properties using a concrete dictionary type other than Dictionary<string, object> or Dictionary<string, JsonElement> should be initialized before deserialization.

Inspired By

https://github.com/tomlm/YamlConvert