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
<PackageReference Include="OfficeIMO.Yaml" Version="3.6.2" />
<PackageVersion Include="OfficeIMO.Yaml" Version="3.6.2" />
<PackageReference Include="OfficeIMO.Yaml" />
paket add OfficeIMO.Yaml --version 3.6.2
#r "nuget: OfficeIMO.Yaml, 3.6.2"
#:package OfficeIMO.Yaml@3.6.2
#addin nuget:?package=OfficeIMO.Yaml&version=3.6.2
#tool nuget:?package=OfficeIMO.Yaml&version=3.6.2
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>()andTryGetValue<T>()forstring,bool,int,long,double,float,decimaland their nullable forms;AsString()for the decoded text;IsNull;YamlScalar.Kindfor what a scalar resolves to (null, boolean, integer, float, string, timestamp, or a custom tag).AsMapping(),AsSequence()andAsScalar()throw an exception naming the actual node kind. Reading never changes the source text.Aliases stay
YamlAliasnodes in the tree. Typed reads andTargetlook 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 ornull, andnode.GetPath()returns a node's path. The grammar matches the pathsOfficeIMO.Reader.Yamlreports:Step Selects name,.nameThe 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 .0or["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
1and"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 thePaththatSelectreads back and the node'sStartposition. 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, so8080matches@.port == 8080but"8080"does not. On a multi-document stream,$[*]or$[?(@.kind == 'Service')]picks documents. JSON loads as YAML, andTomlDocument.Querytakes the same grammar, so one query reads YAML, JSON and TOML (officeimo queryruns it from the command line).Comments:
CommentBeforereturns the comment lines above a node's entry,Commentthe comment at the end of its line, andSpaceBeforewhether a blank line precedes it. A mapping value shares its key's lines.YamlDocumentPart.CommentBeforeandCommentAfterhold a document's header (such as a license) and footer, andYamlDocumentPart.Commentthe comment on its---line (--- # generated by Helm); each has aSet…method.Source positions:
node.StartandEndgive the offset and one-based line and column where a loaded node is in the file, for messages that point at it.IsModifiedtells whether editing changed the node or anything inside it since load; nodes whose content comes from editing have no position (Start.Lineis 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-keywarning inDiagnostics.Strictloads fail withYaml.Load.DuplicateKey, as the specification requires.YamlLoadOptions.DuplicateKeys(Error,FirstWinsorLastWins) overrides both defaults.Custom tags such as
!Refare kept verbatim inTagand 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"] = valueormapping.Set(key, value),sequence[i] = value, andscalar.SetValue(...)take strings, numbers, booleans,nullor nodes. A value equal to the current one under the document's schema keeps its source text: settingtrueonTRUEchanges 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,RemoveAtandRenameKeyonYamlMapping;Add,InsertandRemoveAtonYamlSequence.AddandInsertreturn the node they placed, so configuration chains:SetComment,SetCommentBefore,SetSpaceBefore,SetAnchorandSetTagreturn 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), anddocument.Remove(path)returnsfalsewhen 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- itemorkey:\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 as1.29.2stay 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:
SetAnchorrenames 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; setRoot, use pathSet, orAddDocumentfor 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.YamlFormatterdoes 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:
TRUEstaysTRUEwhen the overlay saystrue. - Sequences follow
YamlMergeOptions.Sequences:YamlSequenceMerge.Replace(the default, as in Helm),Append, orMergeByKey("name"), which merges items with the samenameand 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.Mergemerges into a subtree, such asvalues.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 throwsYamlPatchException(withOperationIndexandPath), 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;movekeeps the moved node's comments and spelling.testcompares 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 amovethat would put an alias before its anchor. - Merge patch merges as
Mergedoes withNullRemovesKey: 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
initones. - 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#
requiredmembers and[OfficeRequired]properties must be present. - Unknown keys are skipped.
- Read-only properties are written but not read.
- Reading sets properties, including
Collections: arrays,
List<T>, the list and set interfaces,HashSet<T>, and other collections with a parameterless constructor andAdd, 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 anint:Type YAML string,chartext, quoted only where a YAML 1.2 or 1.1 reader would see another type ( 'yes','1.0')booltrue,false;yes/onalso read under YAML 1.1integers, BigIntegerdecimal digits; 0x/0o(and YAML 1.1 forms) also readfloat,doubleshortest round-trip digits with a decimal point: 0.1,1.0e+21,.inf,.nandecimalinvariant digits, keeping scale: 1.50DateTimeISO 8601, plain like a YAML timestamp: 2024-05-01T08:30:00Z(UTC), an offset (local) or no zone (unspecified)DateTimeOffset2024-05-01T08:30:00.5+02:00DateOnly,TimeOnly2024-05-01,08:30:00TimeSpan1.02:03:04.5(constant format), quoted where YAML 1.1 reads a sexagesimal number ('12:30:00')Guid0f8fad5b-d9cb-469f-a165-70867728950eUriits original string byte[]!!binarybase64enums member names, read ignoring case; numbers also read [Flags]enumsone scalar Read, Write, asEnum.ToStringwrites 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 becomeDictionary<string, object?>in file order, and sequences becomeList<object?>. Scalars resolve through the document's schema tonull,bool,long(BigIntegerbeyond 64 bits),doubleorstring. 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 placekindafterapiVersion.
[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 | Versions 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. |
-
.NETFramework 4.7.2
- OfficeIMO.Core (>= 3.6.2)
- System.Buffers (>= 4.5.1)
- System.Memory (>= 4.5.5)
-
.NETStandard 2.0
- OfficeIMO.Core (>= 3.6.2)
- System.Buffers (>= 4.5.1)
- System.Memory (>= 4.5.5)
-
net10.0
- OfficeIMO.Core (>= 3.6.2)
-
net8.0
- OfficeIMO.Core (>= 3.6.2)
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 |