OfficeIMO.Yaml 3.6.2

Prefix Reserved
dotnet add package OfficeIMO.Yaml --version 3.6.2
                    
NuGet\Install-Package OfficeIMO.Yaml -Version 3.6.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OfficeIMO.Yaml" Version="3.6.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OfficeIMO.Yaml" Version="3.6.2" />
                    
Directory.Packages.props
<PackageReference Include="OfficeIMO.Yaml" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OfficeIMO.Yaml --version 3.6.2
                    
#r "nuget: OfficeIMO.Yaml, 3.6.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OfficeIMO.Yaml@3.6.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OfficeIMO.Yaml&version=3.6.2
                    
Install as a Cake Addin
#tool nuget:?package=OfficeIMO.Yaml&version=3.6.2
                    
Install as a Cake Tool

OfficeIMO.Yaml

OfficeIMO's own YAML 1.2 engine. It has no runtime dependencies beyond OfficeIMO.Core and targets .NET Standard 2.0, .NET Framework 4.7.2, .NET 8 and .NET 10.

The package provides YamlDocument, a lossless document model you can edit, YamlReader, a forward-only pull reader, YamlWriter, a forward-only emitter, and YamlSerializer, which converts objects with generated or reflection metadata.

Install

dotnet add package OfficeIMO.Yaml

The serializer's source generator ships inside the package, so no second package is needed for trimmed or NativeAOT applications.

To read YAML files through Microsoft.Extensions.Configuration (AddYamlFile), add OfficeIMO.Yaml.Configuration.

Loading a document

using OfficeIMO.Yaml;

using YamlDocument document = YamlDocument.Load("deployment.yaml");
YamlMapping spec = document.Root!.AsMapping()["spec"].AsMapping();
int replicas = spec["replicas"].GetValue<int>();
string? image = document.Select("spec.template.spec.containers[0].image")?.AsString();
document.Save();   // unchanged: the same bytes as the input

YamlDocument.Load reads a file or stream, LoadAsync does the same asynchronously, and Parse takes a string; each accepts a CancellationToken. Use YamlLoadOptions.UntrustedDefaults for files from outside. Create(path) starts an empty document for a file without writing it. FilePath is the file of Create(path), the load or the last Save(path), and Save() writes there; Save(path) replaces the file atomically, and Save(stream) and SaveAsync write elsewhere. The encoding (UTF-8, UTF-16 or UTF-32, either byte order) and byte-order mark are detected and kept, so Save, SaveAsync and ToString() reproduce an unchanged input byte for byte, including comments, blank lines, quoting, key order, line endings and the original spelling of every scalar.

Documents lists every document of a multi-document stream as a YamlDocumentPart with its root, %YAML version, %TAG directives and ---/... markers; Root is the first document's root. Nodes are YamlMapping (ordered entries; string-key lookup), YamlSequence, YamlScalar and YamlAlias. Loading stores nodes as compact records that point into the retained source; node objects are created when code first reaches them, and scalar values are decoded on first use. Dispose a document after its last use: disposing returns its pooled node storage and input bytes, and reaching a node that was not read before then throws ObjectDisposedException.

  • Typed reads go through the document's schema: GetValue<T>() and TryGetValue<T>() for string, bool, int, long, double, float, decimal and their nullable forms; AsString() for the decoded text; IsNull; YamlScalar.Kind for what a scalar resolves to (null, boolean, integer, float, string, timestamp, or a custom tag). AsMapping(), AsSequence() and AsScalar() throw an exception naming the actual node kind. Reading never changes the source text.

  • Aliases stay YamlAlias nodes in the tree. Typed reads and Target look through them to the anchored node.

  • Merge keys (<<) apply to key lookups and paths, without being flattened into the tree: under the YAML 1.1 schema, and also under the default Core schema unless the load is strict (see YAML as real files use it). A mapping's own keys win, then merged mappings in order; repeated << keys form one merge list.

  • Paths: Select("spec.containers[0].image") returns a node or null, and node.GetPath() returns a node's path. The grammar matches the paths OfficeIMO.Reader.Yaml reports:

    Step Selects
    name, .name The value of the key whose decoded text is name, whatever its quoting or type (.0x1F, .true). A name runs to the next . or [.
    ["key"] Any key, with JSON escapes. Needed for keys that contain . or [, are empty or start with $: labels["app.kubernetes.io/name"], ["say \"hi\""].
    ["[a, b]"] A collection key ([a, b]: x), by its YAML text, when no scalar key has that text.
    [n] The zero-based item of a sequence. A numeric mapping key is .0 or ["0"].
    $, $[n] The starting node; on a multi-document YamlDocument, $[n] picks the document.

    Steps follow aliases and merge keys. Keys with equal text resolve as lookups do (the last by default), so of 1 and "1" in one mapping, enumerate the entries to reach the other.

  • Queries: Query(query) returns every node a query selects, in document order, each with the Path that Select reads back and the node's Start position. Every path is also a query; queries add * and [*] (every value or item), .. (the step at any depth: ..image), [-1] (from the end) and filters that compare @ paths with literals: services[?(@.name == 'web')].port, [?(@.port >= 8000 && !@.internal)]. Scalars compare by what they resolve to, so 8080 matches @.port == 8080 but "8080" does not. On a multi-document stream, $[*] or $[?(@.kind == 'Service')] picks documents. JSON loads as YAML, and TomlDocument.Query takes the same grammar, so one query reads YAML, JSON and TOML (officeimo query runs it from the command line).

  • Comments: CommentBefore returns the comment lines above a node's entry, Comment the comment at the end of its line, and SpaceBefore whether a blank line precedes it. A mapping value shares its key's lines. YamlDocumentPart.CommentBefore and CommentAfter hold a document's header (such as a license) and footer, and YamlDocumentPart.Comment the comment on its --- line (--- # generated by Helm); each has a Set… method.

  • Source positions: node.Start and End give the offset and one-based line and column where a loaded node is in the file, for messages that point at it. IsModified tells whether editing changed the node or anything inside it since load; nodes whose content comes from editing have no position (Start.Line is 0).

  • Walking: node.Descendants() enumerates a node and everything below it depth first, without allocating per node.

  • Duplicate keys load by default: the last one wins in lookups, paths and the serializer, every entry stays in the tree (so saving reproduces the file), and each repeat is a yaml-duplicate-key warning in Diagnostics. Strict loads fail with Yaml.Load.DuplicateKey, as the specification requires. YamlLoadOptions.DuplicateKeys (Error, FirstWins or LastWins) overrides both defaults.

  • Custom tags such as !Ref are kept verbatim in Tag and never fail a load.

Editing

using YamlDocument document = YamlDocument.Load("deployment.yaml");
document.Set("spec.replicas", 3);                       // only "3" changes in the file
YamlMapping container = document.Select("spec.template.spec.containers[0]")!.AsMapping();
container.Add("imagePullPolicy", "Always").SetComment("pinned by CI");
container.Remove("command");                            // its comments and lines go with it
document.Add("spec.template.spec.containers[0].ports", new YamlMapping { { "containerPort", 8080 } });
document.Save();

Saving copies every untouched part of the source and writes only what changed, so comments, blank lines, quoting, indentation, key order and spellings such as TRUE or 0x1F survive everywhere else.

  • Values: mapping["key"] = value or mapping.Set(key, value), sequence[i] = value, and scalar.SetValue(...) take strings, numbers, booleans, null or nodes. A value equal to the current one under the document's schema keeps its source text: setting true on TRUE changes nothing. A changed string keeps its style when that style can represent it, and otherwise takes the most conservative one that can.
  • Entries and items: Add, Insert, Remove, RemoveAt and RenameKey on YamlMapping; Add, Insert and RemoveAt on YamlSequence. Add and Insert return the node they placed, so configuration chains: SetComment, SetCommentBefore, SetSpaceBefore, SetAnchor and SetTag return the node.
  • Paths: document.Set(path, value) creates missing mappings on the way, document.Add(path, value) appends to the sequence at a path (creating it), and document.Remove(path) returns false when nothing is there. A path that goes through a scalar throws.
  • New nodes follow their neighbors: the document's mapping indentation, sequence style (key:\n- item or key:\n - item), quoting convention and line endings. Strings are quoted when a YAML 1.2 reader or a YAML 1.1 reader in common use (PyYAML, go-yaml v2, Ruby Psych) could read them as anything but a string (yes, on, 1.5, 012, 1:20); versions such as 1.29.2 stay plain.
  • Removing an entry removes the comment lines directly above it, its lines and its trailing comment; the neighbors keep theirs. A comment block that a blank line separates from the entry, such as a commented-out example, belongs to no entry and stays. A collection left empty is written as [] or {}.
  • Anchors and aliases: SetAnchor renames an anchor together with its aliases, new YamlAlias(node) refers to an anchored node, and removing a node that aliases still use fails. Editing a node that aliases share records a diagnostic, because the change shows through every alias. Setting a key that only a << merge provides adds an entry of its own; merged mappings are never edited.
  • New documents: YamlDocument.Create() starts an empty stream; set Root, use path Set, or AddDocument for multi-document streams.
  • Reformatting: Save(path, new YamlSaveOptions { Reformat = true }) writes the whole document anew through the emitter to normalize its layout, keeping values, anchors, tags and comments outside flow collections. YamlFormatter does the same with layout settings; see Linting and formatting.

Linting and formatting

IReadOnlyList<YamlLintFinding> findings = YamlLinter.Lint(File.ReadAllText("values.yaml"));
foreach (YamlLintFinding finding in findings) Console.WriteLine(finding);   // 12:10 warning Truthy value "yes" ... (truthy)

YamlLintFixResult result = YamlLinter.Fix(text);                            // only the repaired lines change
string formatted = YamlFormatter.Format(text, new YamlFormatOptions { IndentWidth = 2, SequenceIndentation = YamlSequenceIndentation.Indented });

YamlLinter checks text against a rule set modelled on yamllint, with the same rule ids (YamlLintRules). Each YamlLintFinding has the rule id, severity, line and column, a message, and a Fix when the problem can be repaired without changing a value.

Rule Default Fix
syntax Always, error None; the line rules still run
key-duplicates On, error None
indentation On: nested mappings use the file's first width; sequences under keys are all key:\n- item or all key:\n - item None; use the formatter
truthy On: yes, no, on, off in any case; keys are not checked Quoted where the value is a string, true/false under %YAML 1.1
octal-values On: 0755-style integers, which YAML 1.1 and 1.2 readers read differently None
trailing-spaces, comments, empty-lines, new-line-at-end-of-file On Removed, padded or added; never inside block scalar content
line-length On, 120, one long word allowed None
tabs On None
document-start, empty-values, quoted-strings, key-ordering Off --- added; requoted or unquoted

YamlLintOptions turns each rule on or off and sets its severity and settings (Indentation.Spaces, LineLength.Max, Truthy.AllowedValues, QuotedStrings.QuoteType, ...); GetRule(id) finds a rule by its id. YamlLinter.Fix applies the safe fixes as text edits on the original, loads the result again and keeps it only when every value, tag and anchor is the same.

YamlFormatter.Format writes the whole document through the emitter Reformat uses, so values, spellings, anchors, aliases, tags, comments outside flow collections and blank lines above entries stay, and formatting formatted text returns it unchanged. YamlFormatOptions sets the indent width, SequenceIndentation (Preserve, Compact, Indented), Quotes (Preserve, Single, Double; strings that need escapes stay double-quoted), LineEnding and FinalNewline; settings left at their defaults follow the document's own conventions. Format(YamlDocument, options) formats an edited document without changing it. A document loaded with YamlDialect.Unity throws NotSupportedException, because Unity reads only the layout it writes; use YamlLinter.Fix for those files.

The officeimo yaml lint and officeimo yaml format commands of OfficeIMO.Tool run both on files and folders.

Merge overlays

using var values = YamlDocument.Load("values.yaml");
using var production = YamlDocument.Load("values.prod.yaml");
YamlMergeReport report = values.Merge(production, new YamlMergeOptions { NullRemovesKey = true });
values.Save("values.merged.yaml");

foreach (string path in report.Replaced) Console.WriteLine("changed " + path);   // image.tag, resources, ...

With this overlay:

image:
  tag: 1.29.2
resources:
  limits:
    memory: 256Mi
podAnnotations: null   # remove the chart default

the merged file differs from values.yaml only in tag, in resources (a resources: {} placeholder becomes a block mapping) and in the removed podAnnotations entry. Every other comment, blank line and spelling stays as it was.

  • Mappings merge key by key, recursively. Keys the base lacks are appended with the overlay's comments, in the base's indentation and quoting.
  • Scalars are assigned, so a value equal under the schema keeps the base text: TRUE stays TRUE when the overlay says true.
  • Sequences follow YamlMergeOptions.Sequences: YamlSequenceMerge.Replace (the default, as in Helm), Append, or MergeByKey("name"), which merges items with the same name and appends the rest. A replaced sequence changes only the items that differ.
  • Nulls replace by default. With NullRemovesKey, Helm's convention, an overlay null removes the base key.
  • Kind conflicts, such as a mapping replacing a scalar, let the overlay win and are reported.
  • Anchors and aliases: an overlay value that lands on an alias edits the anchored node, which every alias shares, and is reported. Overlay anchors are copied with their names; a name the base already uses is renamed and reported. << merge keys follow the typed view and are never flattened.
  • YamlMapping.Merge merges into a subtree, such as values.Select("ingress")!.AsMapping().Merge(overlay).

YamlMergeReport lists the added, replaced and removed paths in the grammar Select reads, and its Diagnostics hold the conflicts, alias edits and renamed anchors, which are also added to the base document's Diagnostics.

JSON Patch and JSON Merge Patch

using var deployment = YamlDocument.Load("deployment.yaml");
YamlPatchReport report = deployment.ApplyJsonPatch("""
    [
      { "op": "test", "path": "/spec/replicas", "value": 2 },
      { "op": "replace", "path": "/spec/replicas", "value": 3 },
      { "op": "add", "path": "/metadata/labels/env", "value": "prod" }
    ]
    """);
deployment.ApplyMergePatch("""{ "metadata": { "annotations": null } }""");
deployment.Save();

ApplyJsonPatch applies an RFC 6902 patch (add, remove, replace, move, copy, test) and ApplyMergePatch an RFC 7386 merge patch. Both take JSON text, YAML text or a loaded YamlDocument, address the first document of the stream with RFC 6901 pointers, and go through the editing operations, so only the patched lines change.

  • All or nothing: a failed test, a pointer to nothing, a malformed operation or an edit the model refuses throws YamlPatchException (with OperationIndex and Path), and the document is unchanged.
  • Values are copied as their typed view: aliases expanded, << merges flattened, anchors left out, so a JSON patch and the same patch written in YAML do the same thing. New collections take block layout and strings the document's quoting; move keeps the moved node's comments and spelling. test compares as JSON: mappings regardless of key order, numbers by value.
  • Aliases and merge keys: pointers follow aliases and the keys << merges provide. A patch through an alias edits the anchored node and is reported. Setting a key that only a merge provides adds an entry of its own; removing one (or a merge patch null for one) fails, because merged mappings are never edited. Removing or replacing a node that aliases use fails, and so does a move that would put an alias before its anchor.
  • Merge patch merges as Merge does with NullRemovesKey: an equal value keeps its spelling and a replaced sequence changes only the items that differ.

YamlPatchReport lists the added, replaced and removed paths in the grammar Select reads, with the same Diagnostics as a merge.

Validating with JSON Schema

Validate checks a document against a JSON Schema (draft 2020-12 or draft 7), the schemas Kubernetes, GitHub Actions and docker-compose tooling publish. Each finding has the JSON Pointer of the failing value, the schema path of the keyword, a message, and the value's line and column:

using OfficeIMO.Json;
using OfficeIMO.Yaml;

JsonSchema schema = JsonSchema.Parse(File.ReadAllText("deployment.schema.json"));
using var manifest = YamlDocument.Load("deployment.yaml");
foreach (YamlDocumentPart part in manifest.Documents) {
    foreach (JsonSchemaFinding finding in part.Validate(schema).Findings) {
        Console.WriteLine(finding);   // 7:15 /spec/replicas: Expected integer but found string.
    }
}

Values take the type the document's schema resolves, so enabled: yes is a boolean under %YAML 1.1 and a string under the default core schema. Merge keys apply, aliases share their anchored value, and timestamps and custom-tagged scalars stay strings. ToJsonData() on a node, document part or document returns the converted value; a schema written in YAML loads with JsonSchema.Load(schemaDocument.ToJsonData()). References outside the schema resolve only through JsonSchemaOptions.ReferenceResolver. The keywords, formats and limits are described in JSON Schema validation.

Writing YAML

using var writer = new YamlWriter(stream);   // UTF-8 without a byte-order mark
writer.WriteStartMapping();
writer.WriteKey("name");
writer.WriteScalar("web");
writer.WriteKey("enabled");
writer.WriteScalar("yes");                   // written 'yes', so YAML 1.1 readers keep it a string
writer.WriteKey("ports");
writer.WriteStartSequence(YamlStyle.Flow);
writer.WriteScalar(80);
writer.WriteScalar(443);
writer.WriteEndSequence();
writer.WriteEndMapping();

YamlWriter writes to a stream through a pooled UTF-8 buffer or to a TextWriter, and allocates nothing per call beyond that buffer. It covers mappings, sequences, keys, scalars with a requested style, aliases, anchors, tags, comments and document markers, and its output is deterministic. YamlWriterOptions sets the mapping indent, sequence indent and dash offset (2, 2 and 0 write key:\n- item; 2, 4 and 2 write key:\n - item) and the line break. Long lines are never folded, empty collections are written as [] and {}, and multi-line strings become literal block scalars.

Serializing objects

YamlSerializer converts .NET objects to and from YAML. Its API follows System.Text.Json:

using OfficeIMO.Yaml;

var options = new YamlSerializerOptions { PropertyNamingPolicy = OfficeNamingPolicy.CamelCase };
string yaml = YamlSerializer.Serialize(config, options);
AppConfig? copy = YamlSerializer.Deserialize<AppConfig>(File.ReadAllText("app.yaml"), options);

These overloads create metadata by reflection. For trimmed and NativeAOT applications, declare a context and pass its generated metadata. The source generator ships in this package; nothing else is installed:

[YamlSerializable(typeof(AppConfig))]
internal partial class AppYamlContext : YamlSerializerContext { }

var context = new AppYamlContext(new YamlSerializerOptions { PropertyNamingPolicy = OfficeNamingPolicy.CamelCase });
string yaml = YamlSerializer.Serialize(config, context.AppConfig);
AppConfig? copy = YamlSerializer.Deserialize(yaml, context.AppConfig);
object? value = YamlSerializer.Deserialize(yaml, typeof(AppConfig), context);

AppYamlContext.Default uses default options. The context covers the root types and every type they reach. A shape the serializer cannot handle is a build error (YAML001 to YAML005), not a runtime failure. In a PublishAot or PublishTrimmed application the reflection overloads are off. Without generated metadata they throw an exception that names the context to add. Set the YamlSerializerIsReflectionEnabledByDefault MSBuild property to change this.

Serialization reads from YamlReader and writes to YamlWriter directly, without building a tree. Every method takes a string, a Stream, a TextReader or TextWriter, or a reader or writer:

  • Deserialize(reader, ...) reads the next document's root, so a loop reads a multi-document stream such as a Kubernetes manifest. On a node event it reads just that node.
  • Serialize(writer, ...) writes one node at the writer's position. String, stream and text-reader input must hold one document.

Supported types

  • Objects: classes, structs and records, with public properties that have a public getter. Base-class properties come first.

    • Reading sets properties, including init ones.
    • It uses the public parameterless constructor, the only public constructor, or the one marked [OfficeConstructor]. Constructor parameters bind to properties of the same name and type, ignoring case.
    • C# required members and [OfficeRequired] properties must be present.
    • Unknown keys are skipped.
    • Read-only properties are written but not read.
  • Collections: arrays, List<T>, the list and set interfaces, HashSet<T>, and other collections with a parameterless constructor and Add, written as sequences.

  • Dictionaries: Dictionary<TKey, TValue>, IDictionary<,>, IReadOnlyDictionary<,>, and other dictionaries with a parameterless constructor, written as mappings. Keys are strings, numbers, enums or other scalars.

  • Scalars, read by their target type whatever their quoting, so "8080" reads into an int:

    Type YAML
    string, char text, quoted only where a YAML 1.2 or 1.1 reader would see another type ('yes', '1.0')
    bool true, false; yes/on also read under YAML 1.1
    integers, BigInteger decimal digits; 0x/0o (and YAML 1.1 forms) also read
    float, double shortest round-trip digits with a decimal point: 0.1, 1.0e+21, .inf, .nan
    decimal invariant digits, keeping scale: 1.50
    DateTime ISO 8601, plain like a YAML timestamp: 2024-05-01T08:30:00Z (UTC), an offset (local) or no zone (unspecified)
    DateTimeOffset 2024-05-01T08:30:00.5+02:00
    DateOnly, TimeOnly 2024-05-01, 08:30:00
    TimeSpan 1.02:03:04.5 (constant format), quoted where YAML 1.1 reads a sexagesimal number ('12:30:00')
    Guid 0f8fad5b-d9cb-469f-a165-70867728950e
    Uri its original string
    byte[] !!binary base64
    enums member names, read ignoring case; numbers also read
    [Flags] enums one scalar Read, Write, as Enum.ToString writes it; YamlDotNet and SharpYaml read it too, and reading also accepts [Read, Write]

    A value no enum member names is written as its number.

  • Nullable value types: null, or the value.

  • object: values are written by their runtime type: dictionaries, lists, scalars and types the metadata source knows. Values read as plain .NET values. Mappings become Dictionary<string, object?> in file order, and sequences become List<object?>. Scalars resolve through the document's schema to null, bool, long (BigInteger beyond 64 bits), double or string. Timestamps and custom tags stay strings.

  • Polymorphism only through registrations on the base type. A tag in the input never names a .NET type by itself:

    [OfficeDerivedType(typeof(HttpProbe), "http")]
    [OfficeDerivedType(typeof(TcpProbe), "tcp")]
    public abstract class Probe { }
    

    The discriminator is a local tag (- !http {path: /health}). With [OfficePolymorphic(DiscriminatorPropertyName = "kind")] it is written as the first key instead, and reading finds it anywhere in the mapping, as Kubernetes files place kind after apiVersion.

[OfficePropertyName] sets a key and wins over the naming policy. The policies are CamelCase, SnakeCaseLower and KebabCaseLower. [OfficeIgnore] leaves a property out. Its Condition, or YamlSerializerOptions.DefaultIgnoreCondition, skips only null or default values when writing. These attributes, OfficeNamingPolicy and OfficeIgnoreCondition are in the OfficeIMO namespace (OfficeIMO.Core), and TomlSerializer in OfficeIMO.Toml reads the same ones, so one model maps to both formats.

Anchors, aliases and merge keys

Reading an alias as object returns the dictionary, list or scalar already read for its anchor, as PyYAML does, so changing it changes every place that shares it; set CopyAliases for a copy per alias. A typed value is read again from the anchored node for each alias. Either way every alias counts the nodes it stands for against MaxAliasExpansion of the reader options, because writing or walking a shared value visits them all. YamlReaderOptions.UntrustedDefaults lowers every limit for input from outside. << merge keys fill only the members a mapping does not set itself.

Writing has no reference handling by default, and a cycle throws YamlErrorCodes.ReferenceCycle. With ReferenceHandling = YamlReferenceHandling.Preserve, an object reached again is written as an alias (*id001) to an anchor on its first occurrence. Reading then maps each alias back to the same instance, so shared references and cycles round-trip.

Typed sections in documents

SerializeToNode returns a detached YamlNode tree, and Deserialize(YamlNode, ...) reads one. Together they mix typed sections with lossless edits:

using YamlDocument document = YamlDocument.Load("values.yaml");
var resources = YamlSerializer.Deserialize(document.Select("resources")!, context.Resources)!;
resources.Limits["memory"] = "512Mi";
document.Set("resources", YamlSerializer.SerializeToNode(resources, context.Resources));
document.Save();   // only the resources section is rewritten; comments elsewhere stay

Errors

Input that does not fit the model throws YamlException with code TypeMismatch, MissingRequiredMember, DuplicateKey or UnknownDiscriminator. The position points at the node. The message names its path (at spec.containers[0].ports), even inside a loaded document.

YAML as real files use it

By default the reader and the loader read three forms the way real files use them and libyaml (behind PyYAML and Ruby) and SharpYaml read them, where the YAML 1.2.2 specification rejects them or reads them differently. Lines inside a flow collection and quoted-scalar continuation lines may be indented no deeper than the enclosing block collection, and << merges under the Core schema:

args: [
  --verbose
]                     # a flow collection's lines at the key's indentation
message: 'first line
second line'          # a quoted scalar's continuation at the key's indentation
job:
  <<: *defaults       # merge keys without a %YAML 1.1 directive (docker-compose, GitLab CI)
  <<: *extra          # repeated merge keys add to one merge list

Each accepted indentation is a yaml-lenient-indentation warning with its line and column, once per outermost flow collection and once per quoted scalar, in YamlReader.Diagnostics and YamlDocument.Diagnostics. A document part that uses merge keys without a %YAML 1.1 directive gets one yaml-merge-key-without-directive information note in YamlDocument.Diagnostics. Indentation that a tab provides is still rejected. YamlReader.Diagnostics is empty and allocation-free until a finding occurs.

Set Strict on YamlReaderOptions or YamlLoadOptions for the specification's exact rules: both indentation forms are syntax errors, and << is an ordinary key unless the YAML 1.1 schema applies, so a repeated one is a duplicate key.

Saving copies accepted text that an edit does not own unchanged. New and edited text is always written in the valid form.

Unity files

Unity's scenes, prefabs, assets and .meta files are YAML 1.1 with two departures from the specification: %TAG !u! tag:unity3d.com,2011: is declared once for the whole file, and a prefab placeholder ends its --- line with stripped. Load them with YamlDialect.Unity:

using YamlDocument scene = YamlDocument.Load("Main.unity", new YamlLoadOptions { Dialect = YamlDialect.Unity });
foreach (YamlDocumentPart part in scene.Documents) {
    // part.Root.Tag is "tag:unity3d.com,2011:1" for a GameObject; part.Root.Anchor is its fileID.
    if (part.IsStripped) continue;
    if (part.Root.AsMapping().TryGetValue("GameObject", out YamlNode? node) && node is YamlMapping gameObject
        && gameObject["m_Name"].AsString() == "Main Camera") {
        gameObject.Set("m_Name", "Player Camera");
    }
}
scene.Save();   // only the edited line changes

Every document reads with the YAML 1.1 schema unless Schema is set, a document without %TAG directives resolves tags with the ones before it (its TagDirectives stays empty, as in the file), and IsStripped on YamlDocumentPart and YamlReader reports the placeholder marker. Saving keeps both departures: edits change only their lines, and an edited tag or anchor on a --- line keeps the !u! handle, its order and stripped. Reformatting a Unity file throws NotSupportedException, because Unity reads only its own layout. The Standard dialect still rejects these files.

Reading events

using OfficeIMO.Yaml;

using var reader = new YamlReader("""
    name: web
    replicas: 3
    ports: [80, 443]
    """);

while (reader.Read()) {
    if (reader.TokenType == YamlTokenType.Scalar) {
        if (reader.TryGetInt64(out long number)) Console.WriteLine($"{reader.Start}: int {number}");
        else Console.WriteLine($"{reader.Start}: {reader.GetString()}");
    }
}

Read() moves through stream, document, mapping, sequence, scalar and alias events. The reader allocates nothing per event; strings are created only when you call GetString(), Tag or Anchor. ValueSpan exposes the raw source text of the current value without copying.

Readers accept a string, ReadOnlyMemory<char>, TextReader or Stream. Stream input detects UTF-8, UTF-16 and UTF-32 (either byte order) from the byte-order mark or the first bytes, as the specification requires. Stream and TextReader input is read through a pooled sliding buffer. The reader never disposes the stream or text reader you pass in.

Typed values and schemas

TryGetBoolean, TryGetInt64, TryGetDouble, TryGetDecimal and IsNull resolve untagged plain scalars through the document's schema. Quoted and block scalars are strings unless they carry an explicit tag such as !!int.

Schema Resolves
Core (default) null, ~, empty; true/false in three casings; decimal, 0o and 0x integers; floats, .inf, .nan
Json null, true, false and JSON numbers only
Failsafe nothing; every scalar is a string
Yaml11 yes/no/on/off/y/n, 0b and 0-octal integers, underscores, sexagesimal numbers

A %YAML 1.1 directive selects Yaml11 for that document. YamlReaderOptions.Schema and YamlLoadOptions.Schema force one schema for every document, for tools that assume YAML 1.1 without declaring it.

Comments

Set YamlReaderOptions.IncludeComments to receive YamlTokenType.Comment events in source order. Comments cost nothing when the option is off.

Options

Options Used by Settings
YamlLoadOptions YamlDocument.Load, LoadAsync, Parse Schema, Strict, DuplicateKeys and the limits below; UntrustedDefaults
YamlReaderOptions YamlReader, YamlSerializerOptions.ReaderOptions Schema, Strict, IncludeComments and the limits below; UntrustedDefaults
YamlSaveOptions Save, SaveAsync Reformat, WriterOptions
YamlWriterOptions YamlWriter, YamlSerializerOptions.WriterOptions MappingIndent, SequenceIndent, SequenceDashOffset, NewLine
YamlMergeOptions YamlDocument.Merge, YamlMapping.Merge Sequences, NullRemovesKey
YamlSerializerOptions YamlSerializer, YamlSerializerContext PropertyNamingPolicy, DefaultIgnoreCondition, ReferenceHandling, ReaderOptions, WriterOptions, TypeInfoResolver

UntrustedDefaults returns a new instance with lower limits for files from outside: 16 MiB of input, depth 64, 200,000 nodes, 10,000 alias-expanded nodes and 1 MiB scalars. Strict and DuplicateKeys are described in YAML as real files use it and under Duplicate keys.

Errors and limits

Malformed input throws YamlException with a stable Code (see YamlErrorCodes), line, column and offset; when the source text is at hand, the message ends with the offending line and a caret under the column. ToDiagnostic() returns the failure as an error OfficeDiagnostic with the catalog code (Yaml.Syntax.InvalidIndentation becomes yaml-syntax-invalid-indentation, a strict duplicate key yaml-duplicate-key) and a line:column location, so a tool can report files that fail next to the warnings of files that load:

using OfficeIMO;
using OfficeIMO.Yaml;

IReadOnlyList<OfficeDiagnostic> diagnostics;
try {
    diagnostics = YamlDocument.Load(path).Diagnostics;
} catch (YamlException exception) {
    diagnostics = new[] { exception.ToDiagnostic() };
}

YamlReaderOptions and YamlLoadOptions bound nesting depth (MaxDepth, 256), scalar length (MaxScalarLength, 16 MiB of characters) and optionally the whole input (MaxInputBytes). YamlLoadOptions also bounds the nodes of each document (MaxNodes, 10,000,000; 200,000 in UntrustedDefaults) and the nodes each document's aliases stand for when resolved (MaxAliasExpansion, 100,000). The load measures expansion without expanding anything, so a "billion laughs" input fails quickly, and an alias inside its own anchor fails with YamlErrorCodes.RecursiveAlias. Exceeding a limit throws YamlLimitExceededException with the limit's name. A CancellationToken passed to the reader constructor or LoadAsync is checked at bounded intervals.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 is compatible.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on OfficeIMO.Yaml:

Package Downloads
OfficeIMO.Markdown

Markdown builder, typed reader/AST, and HTML renderer for .NET with GitHub-like output and an optional portable reader profile.

OfficeIMO.Reader.Yaml

YAML adapter extensions for OfficeIMO.Reader.

OfficeIMO.Data.Conversions

Streaming structured-data conversions between JSON, JSON Lines, YAML, TOML, XML, CSV and TSV for OfficeIMO, with loss reporting through OfficeConversionReport.

OfficeIMO.Yaml.Configuration

YAML configuration provider for Microsoft.Extensions.Configuration, built on the OfficeIMO.Yaml engine: AddYamlFile and AddYamlStream with merge keys, aliases and positioned errors.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.6.2 1,428 11/18/2026