OfficeIMO.Toml
3.6.2
Prefix Reserved
dotnet add package OfficeIMO.Toml --version 3.6.2
NuGet\Install-Package OfficeIMO.Toml -Version 3.6.2
<PackageReference Include="OfficeIMO.Toml" Version="3.6.2" />
<PackageVersion Include="OfficeIMO.Toml" Version="3.6.2" />
<PackageReference Include="OfficeIMO.Toml" />
paket add OfficeIMO.Toml --version 3.6.2
#r "nuget: OfficeIMO.Toml, 3.6.2"
#:package OfficeIMO.Toml@3.6.2
#addin nuget:?package=OfficeIMO.Toml&version=3.6.2
#tool nuget:?package=OfficeIMO.Toml&version=3.6.2
OfficeIMO.Toml
OfficeIMO's own TOML 1.1 engine. It reads, edits and writes TOML without changing anything you didn't change, 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 TomlDocument, a lossless editable model, TomlReader, a forward-only pull reader, TomlWriter, a forward-only emitter, and TomlSerializer, which maps .NET objects to TOML with a NativeAOT source generator.
To read TOML files through Microsoft.Extensions.Configuration (AddTomlFile), add OfficeIMO.Toml.Configuration.
Loading and editing a document
using OfficeIMO.Toml;
using var document = TomlDocument.Load("pyproject.toml");
string name = document.Select("project.name")!.AsString();
int lineLength = document.Select("tool.ruff.line-length")?.GetValue<int>() ?? 88;
document.Set("project.version", "1.2.0"); // only the version text changes
document.Select("project.dependencies")!.AsArray().Add("httpx"); // a new line in the array's own layout
document.Set("tool.ruff.line-length", 100); // adds [tool.ruff] if it is missing
document.Save(); // back to pyproject.toml
TomlDocument.Load reads a file or stream, LoadAsync does the same asynchronously, and Parse takes a string. Create() starts an empty document. Save() writes to the document's FilePath, the file it was loaded from, created for or last saved to; Save(path) replaces a file atomically and makes it the FilePath. Save(stream), SaveAsync and ToString() are also available. Saving an unchanged document reproduces the input byte for byte, including comments, blank lines, quoting, key order, alignment, line endings, a UTF-8 byte-order mark and the original spelling of every value (0xFF, 1_000, 1979-05-27 07:32:00Z).
Root is the root table. Nodes are:
TomlTable: the root, a[table], an inline table, a table made by dotted keys, or one table of an array of tables (TableKindsays which). Keys are unique and keep source order.TomlTableArray: the tables of the[[name]]headers with one name, such as the[[package]]entries of a lock file.TomlArray: an array value in brackets.TomlValue: a string, integer, float, boolean or date-time.Kindtells which;Valueis the decodedstring,long,double,boolorTomlDateTime.
A table is one object even when the file spreads it out: [a], [a.b] and a.c = 1 lines all contribute to the same tree.
- Typed reads:
GetValue<T>()andTryGetValue<T>()forstring,bool,int,long,double,float,decimal,TomlDateTime,DateTime,DateTimeOffsetandTimeSpan, plusDateOnlyandTimeOnlyon .NET 8 and later.AsString()returns a string's text, or the TOML spelling of any other value.AsTable(),AsArray(),AsTableArray()andAsValue()throw an exception naming the actual kind. - Paths:
Select("tool.ruff.line-length")returns a node ornull. Use["key"]with JSON escapes for keys containing dots or brackets, and[n]for array items and the tables of an array of tables (package[3].name).Set(path, value)andRemove(path)edit by path. The grammar matches the pathsOfficeIMO.Reader.Tomlreports. - Queries:
Query(query)returns every node a query selects, in document order, each with itsPathand the node'sStartposition. Queries extend paths with*and[*],..(any depth:..version),[-1]and filters:package[?(@.name == 'serde')].version,dependencies[?(@.optional == true)]. The grammar is the oneYamlDocument.Querytakes, so one query reads TOML, YAML and JSON (officeimo queryruns it from the command line). - Positions:
StartandEndlocate a loaded node in the text, andKeyStartandKeyEndthe key segment that names it (for a table made by dotted keys or deeper headers, its segment of the first such key). Nodes added by editing have the default position, whoseLineis 0. - Comments:
LeadingCommentsreturns the comment lines directly above a node, andTrailingCommentthe comment after it.SetComment(text)sets, replaces or removes the comment after a key/value pair or table header. - Dates and times:
TomlDateTimekeeps all four TOML kinds (offset date-time, local date-time, local date, local time) with nanosecond precision, and converts toDateTimeOffset,DateTimeandTimeSpan.
Editing
Every editing method returns the node it creates or changes, so calls chain: table.Add("version", "1.0").SetComment("pinned").
| Method | Effect on save |
|---|---|
TomlValue.SetValue(value) |
Only the value's text changes. An equal value keeps the original spelling; otherwise the current style is kept when it can hold the new value: hexadecimal stays hexadecimal, a literal string stays literal, a date-time keeps its T or space. |
TomlTable.Add(key, value) / Set(key, value) |
A key = value line after the table's last pair, with its indentation and = spacing. Inside an inline table, an entry inside the braces. New strings follow the quoting of their siblings. |
TomlTable.AddTable(key) / AddTableArray(key) |
A [header] or [[header]] section after the table's last section, separated by a blank line when the file does that. |
TomlTable.AddArray(key) / AddInlineTable(key) |
key = [] or key = {} to fill. |
TomlArray.Add / Insert / Set / RemoveAt |
In the array's own layout (Set at the array's count appends, as does a path Set such as deps[3] on a three-item array): a new line with the same indentation and comma style in a multi-line array, , item on one line otherwise. |
TomlTable.Remove(key) / TomlTableArray.RemoveAt(i) |
The key/value line with the comment lines directly above it, or a table's sections, wherever in the file they are. |
SetComment(text) |
Only the comment after the node changes. |
Values passed to Add and Set can be strings, booleans, integers, floating-point numbers, TomlDateTime, DateTime, DateTimeOffset, DateOnly, TimeOnly, sequences (arrays) and dictionaries with string keys (inline tables). TOML has no null; passing null throws.
New text uses the document's line endings. Text written by OfficeIMO stays readable by TOML 1.0 parsers: strings never use the 1.1-only \e and \x escapes, and times always have seconds.
Merging layered files
Merge deep-merges an overlay document into a base document, as layered configuration does with a shared pyproject.toml and local overrides. Tables merge key by key whatever their syntax, values are assigned (an equal value keeps the base's spelling), and saving writes only what changed, so the base keeps its comments and layout.
using var config = TomlDocument.Load("pyproject.toml");
using var local = TomlDocument.Load("pyproject.local.toml");
TomlMergeReport report = config.Merge(local);
config.Save();
// report.Added, report.Replaced: paths such as tool.ruff.line-length
TomlMergeOptions.Arrays chooses how arrays combine: TomlArrayMerge.Replace (the default), Append, or MergeByKey("name") to match [[package]] tables of a lock file by name and append the rest. When a value changes kind, such as a table over a string, the overlay wins and report.Diagnostics lists a toml-merge-kind-conflict warning. TOML has no null, so where tables merge an overlay cannot remove a key; only a replaced array drops the items, and keys of table items, that the overlay's array lacks.
ApplyJsonPatch applies an RFC 6902 JSON Patch and ApplyMergePatch an RFC 7386 JSON Merge Patch, both given as JSON text, through the same editing operations, so only the patched lines change:
using var project = TomlDocument.Load("pyproject.toml");
TomlPatchReport report = project.ApplyJsonPatch("""
[
{ "op": "test", "path": "/project/version", "value": "1.4.0" },
{ "op": "replace", "path": "/project/version", "value": "1.5.0" },
{ "op": "add", "path": "/project/dependencies/-", "value": "click" }
]
""");
project.ApplyMergePatch("""{ "tool": { "ruff": { "line-length": 100, "exclude": null } } }""");
project.Save();
RFC 6901 pointers address tables by key and arrays and arrays of tables by index. A patch is all or nothing: a failed test, a pointer to nothing or an edit that cannot be made throws TomlPatchException and leaves the document unchanged. Objects become [header] tables and arrays of objects [[header]] arrays of tables (inline tables inside inline tables and arrays), and an array of tables takes new tables only at its end. TOML has no null, so a null value fails a JSON Patch, while a merge patch null removes the key. TomlPatchReport lists the added, replaced and removed paths.
Validating with JSON Schema
Validate checks a document against a JSON Schema (draft 2020-12 or draft 7), such as the published pyproject.toml or Cargo.toml schemas. Tables are objects, arrays of tables are arrays, and dates and times are their RFC 3339 text. Offset date-times satisfy "format": "date-time" and local dates satisfy "format": "date"; local times and local date-times have no offset, so time and date-time reject them. Findings carry the JSON Pointer, line and column of each failing value:
using OfficeIMO.Json;
JsonSchema schema = JsonSchema.Parse(File.ReadAllText("pyproject.schema.json"));
using var project = TomlDocument.Load("pyproject.toml");
foreach (JsonSchemaFinding finding in project.Validate(schema).Findings) {
Console.WriteLine(finding); // 3:11 /project/requires-python: Expected string but found number.
}
ToJsonData() on a node or the document returns the converted value. The keywords, formats and limits are described in JSON Schema validation.
Reading tokens
using OfficeIMO.Toml;
var reader = new TomlReader(File.ReadAllText("Cargo.toml"));
while (reader.Read()) {
if (reader.TokenType == TomlTokenType.Key) Console.Write(reader.GetString() + " ");
else if (reader.TokenType == TomlTokenType.String) Console.WriteLine("= " + reader.GetString());
}
Read() moves through header brackets, key segments, values, array and inline-table brackets and, with TomlReaderOptions.IncludeComments, comments. A dotted key a.b.c = 1 reads as three Key tokens followed by the value. The reader allocates nothing per token; strings are created only when you call GetString(), and ValueSpan exposes the source text of the current token without copying. GetInt64, GetDouble, GetBoolean and GetDateTime decode values.
The reader checks TOML 1.1 syntax completely. Rules that need the whole document, such as duplicate keys and table redefinition, are checked by TomlDocument.
The reader also reads a Stream (UTF-8, with or without a byte-order mark) or a TextReader without loading the whole input, which suits very large lock files:
using var stream = File.OpenRead("Cargo.lock");
using var reader = new TomlReader(stream);
int packages = 0;
while (reader.Read()) {
if (reader.TokenType == TomlTokenType.ArrayOfTablesHeaderStart) packages++;
}
It keeps whole lines in a pooled buffer that grows only while one line or multi-line string is longer than it. Tokens, positions and errors are the same as for the same text in memory, and invalid UTF-8 fails with TomlErrorCodes.InvalidEncoding at the first bad byte. ValueSpan is valid until the next Read(). Dispose the reader to return its buffers; it never disposes your stream or text reader. TomlReaderOptions.MaxInputBytes bounds the input (bytes for a stream, characters otherwise). TomlDocument.Load keeps the whole text, because saving reproduces it.
Writing
using var writer = new TomlWriter(stream);
writer.WriteKey("name");
writer.WriteString("officeimo");
writer.WriteTableHeader("tool", "ruff");
writer.WriteKey("line-length");
writer.WriteInteger(120);
TomlWriter writes headers, keys (dotted with several arguments), values, arrays and inline tables in order and rejects calls TOML does not allow at that point. Output is deterministic. Comments written just before a header stay directly above it, with the blank line that separates sections above the comments. TomlWriterOptions.NewLine selects \n (the default) or \r\n.
Serializing objects
TomlSerializer converts .NET objects to and from TOML documents. Its API follows System.Text.Json and YamlSerializer, and it reads the same mapping attributes, naming policy and ignore condition, which live in the OfficeIMO namespace, so one model maps to YAML and TOML alike:
using OfficeIMO;
using OfficeIMO.Toml;
var options = new TomlSerializerOptions { PropertyNamingPolicy = OfficeNamingPolicy.KebabCaseLower };
CargoManifest manifest = TomlSerializer.Deserialize<CargoManifest>(File.ReadAllText("Cargo.toml"), options);
string toml = TomlSerializer.Serialize(manifest, options);
using var document = TomlDocument.Load("pyproject.toml");
RuffSettings ruff = TomlSerializer.Deserialize<RuffSettings>(document.Select("tool.ruff")!, 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:
[TomlSerializable(typeof(CargoManifest))]
internal partial class CargoContext : TomlSerializerContext { }
var context = new CargoContext(new TomlSerializerOptions { PropertyNamingPolicy = OfficeNamingPolicy.KebabCaseLower });
CargoManifest manifest = TomlSerializer.Deserialize(text, context.CargoManifest);
string toml = TomlSerializer.Serialize(manifest, context.CargoManifest);
A shape the serializer cannot handle is a build error (TOML001 to TOML005). In a PublishAot or PublishTrimmed application the reflection overloads are off; set the TomlSerializerIsReflectionEnabledByDefault MSBuild property to change this. Every method takes a string, a UTF-8 Stream, or a TextReader/TextWriter; Deserialize also takes any TomlNode of a loaded document.
Layout
A TOML document is a table, so the root is an object or a dictionary. Writing puts each table's key/value pairs first and its tables after them, as TOML requires:
version = "1.2.0"
[package]
name = "demo"
[dependencies]
serde = { version = "1", features = ["derive"] }
[[bin]]
name = "cli"
path = "src/main.rs"
[profile.release]
lto = true
- Objects and dictionaries are
[table]sections. A table with only sub-tables gets no header of its own ([profile.release]without[profile]). - A non-empty collection of objects is an array of tables (
[[bin]]); an empty one isbin = []. - Inside an array or inline table everything is inline:
owner = { name = "Ada", address = { city = "London" } }. [TomlInlineTable]on a class or struct writes its values as inline tables, as Cargo dependencies are written. On a property it writes that property's object or collection of objects inline, or, for a dictionary, keeps the dictionary's section and writes its entries inline.
Reading accepts every form for every type: an array of tables or an array of inline tables reads into the same list.
Supported types
Objects: classes, structs and records with public properties, as
YamlSerializermaps them:initproperties, the parameterless, only or[OfficeConstructor]constructor with parameters bound by name, C#requiredand[OfficeRequired]members,[OfficePropertyName]and[OfficeIgnore]. Unknown keys are skipped.Collections: arrays,
List<T>, the list and set interfaces,HashSet<T>, and other collections with a parameterless constructor andAdd.Dictionaries: tables. Keys are strings, or numbers, enums and other scalars written as their text (
[ports]with8080 = "web").Scalars:
Type TOML string,char,Guid,Uristring boolboolean integer types, BigIntegerinteger; a whole float in range also reads. Values outside the 64-bit signed range fail with UnrepresentableValuedouble,floatfloat, including inf,-infandnan; an integer also readsdecimalfloat with its exact digits ( 0.1), read from the text without going through a doubleDateTimeOffsetoffset date-time 1979-05-27T07:32:00-07:00DateTimelocal date-time 1979-05-27T07:32:00; a UTC or local kind is an offset date-time. An offset date-time reads as its UTC instant, a local date as midnightDateOnly,TimeOnlylocal date 1979-05-27, local time07:32:00TimeSpanlocal time when it is a time of day, otherwise the string "1.02:03:04"; both readTomlDateTimeany of the four kinds, unchanged byte[]Base64 string enums member names; [Flags]combinations as"Read, Write", and an array of names also readsNullable value types read and write the value. TOML has no null: a null property or dictionary value is left out, so it reads back as the default. Set
TomlSerializerOptions.NullHandlingtoErrorto fail instead. A null array item always fails withUnrepresentableValue, because leaving it out would shift the items after it.object: tables read asDictionary<string, object?>, arrays and arrays of tables asList<object?>, and values asstring,long,double,boolorTomlDateTime, which keeps the date-time kind.Polymorphism through
[OfficeDerivedType]registrations on the base type. TOML has no tags, so the discriminator is the first key,"$type" = "http", or the key[OfficePolymorphic(DiscriminatorPropertyName = "kind")]names. Reading finds it anywhere in the table; an unknown discriminator fails withUnknownDiscriminator.
Reading applies every TOML rule and the limits in TomlSerializerOptions.LoadOptions, as TomlDocument does. A value that does not fit its type fails with TomlException code TypeMismatch, its line and column, and its path, such as tool.ruff.lint.select[1]. A missing required key fails with MissingRequiredMember; an object that contains itself fails with ReferenceCycle.
Safety and errors
Invalid input throws TomlException with a stable Code from TomlErrorCodes, plus Line, Column and Position; ToDiagnostic() returns the failure as an error OfficeDiagnostic (code toml-load-duplicate-key for Toml.Load.DuplicateKey, location line:column) to report next to other documents' findings. TomlLoadOptions bounds nesting depth (256), node count (1,000,000), string length (16 MiB) and, when set, input size; exceeding a limit throws TomlLimitExceededException naming the limit. Use TomlLoadOptions.UntrustedDefaults for files from outside: 16 MiB of input, depth 64, 200,000 nodes and 1 MiB per string. Loading checks cancellation at bounded intervals.
Conformance
The engine passes all 214 valid and 467 invalid TOML 1.1 cases of toml-test 2.2.0, and every valid case and real-world corpus file (pyproject.toml, Cargo.toml, Cargo.lock, uv.lock, Hugo, Netlify, Starship) saves back byte for byte. An opt-in run over about 5,400 pinned real-world files (crates.io and workspace manifests, lock files, pyproject.toml, Hugo sites) also checks stream reading, scripted edits and hostile mutations; the TOML engine design has the results and the benchmark comparison with Tomlyn.
| 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.6.1)
- System.Memory (>= 4.6.3)
-
.NETStandard 2.0
- OfficeIMO.Core (>= 3.6.2)
- System.Buffers (>= 4.6.1)
- System.Memory (>= 4.6.3)
-
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.Toml:
| 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.Data.Conversions
Streaming structured-data conversions between JSON, JSON Lines, YAML, TOML, XML, CSV and TSV for OfficeIMO, with loss reporting through OfficeConversionReport. |
|
|
OfficeIMO.Reader.Toml
TOML adapter extensions for OfficeIMO.Reader: pyproject.toml, Cargo.toml, lock files and other TOML configuration as path, type and value chunks. |
|
|
OfficeIMO.Toml.Configuration
TOML configuration provider for Microsoft.Extensions.Configuration, built on the OfficeIMO.Toml engine: AddTomlFile and AddTomlStream with TOML 1.1 tables, arrays of tables, ISO 8601 date-times and positioned errors. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.6.2 | 1,385 | 11/18/2026 |