Introduction
Almost every modern Delphi application needs a way to store structured data: configuration settings, runtime options, or even project metadata. For decades, developers have relied on INI files for simple key/value storage, XML for deeply structured documents, or JSON as a lightweight alternative.
But there’s another option that has grown into the de facto standard in DevOps and configuration management: YAML.
This article introduces VSoft.YAML - an open-source Delphi library that makes working with YAML straightforward. We’ll cover why you might choose YAML over INI, XML, or JSON, then dive into practical Delphi code examples for parsing, editing, and writing YAML.
Why YAML?
Human-Readability
YAML is designed for humans first. Compare the following formats describing a database configuration:
YAML
database:
host: localhost
port: 5432
user: admin
password: secret
JSON
{
"database": {
"host": "localhost",
"port": 5432,
"user": "admin",
"password": "secret"
}
}
XML
localhost
5432
admin
secret
The YAML version is the least noisy, especially when configurations get larger.
Expressiveness
- Supports mappings (key/value), sequences (lists), and scalars (strings, numbers, booleans).
- Handles deeply nested structures naturally.
- More flexible than INI files, which are limited to sections and key/value pairs.
Adoption
- YAML is everywhere, especially in DevOps.
Introducing VSoft.YAML
VSoft.YAML is a pure Delphi implementation of a YAML 1.2 parser and emitter:
- No external dependencies — just add the source to your project.
- Round-trip capable — parse, modify, and write YAML without losing formatting.
- Supports multiple documents in a single YAML stream.
- Supports reading/writing JSON
- Extensive JSONPath support
Getting Started
Installation
Clone the repo or add it as a Git submodule:
git clone https://github.com/VSoftTechnologies/VSoft.YAML.git
Then add the VSoft.YAML\Source folder to your Delphi project’s search path.
Parsing YAML
The most common scenario is loading YAML from a string or file.
uses
VSoft.YAML;
var
Doc: IYAMLDocument;
YamlText: string;
begin
YamlText :=
'database:' + sLineBreak +
' host: localhost' + sLineBreak +
' port: 5432' + sLineBreak +
' user: admin' + sLineBreak +
' password: secret';
Doc := TYAML.LoadFromString(YamlText);
Writeln('Database host: ', Doc.Root.Values['database'].Values['host'].AsString);
Writeln('Database port: ', Doc.Root.Values['database'].Values['port'].AsInteger);
end;
To load from a file, just call TYAML.LoadFromFile
Traversing Sequences
YAML supports lists (called sequences).
Example YAML
servers:
- name: web01
ip: 10.0.0.1
- name: web02
ip: 10.0.0.2
Delphi Code
var
doc : IYAMLDocument;
servers: IYAMLSequence;
server : IYAMLMapping;
i: integer;
begin
doc := TYAML.LoadFromFile('c:\test\config.yaml');
servers := Doc.Root.Values['servers'].AsSequence;
for i := 0 to servers.Count - 1 do
begin
server := Servers.Items[I].AsMapping;
Writeln(Format('%s (%s)',[server.Values['name'].AsString, Server.Values['ip'].AsString]));
end;
end;
Modifying YAML
Once parsed, you can update values and write them back out:
var
root: IYAMLMapping;
begin
root := Doc.Root.AsMapping;
root.AddOrSetValue('environment', 'production');
TYAML.WriteToFile(doc, 'c:\test\config.yaml')
end;
Practical Use Cases for Delphi Developers
- Configuration files — ship your app with config.yaml instead of INI or XML.
- DevOps integration — generate or consume YAML configs for devops tools.
- Structured data — when you need nested lists or dictionaries without verbosity.
- Collaboration — YAML files are easy for non-developers to read and edit.
Tips and Best Practices
- Use JSON when machine-only consumption is expected.
- Use YAML when humans will edit the config.
YAML Rules to be aware of
Even though YAML is designed to be human-friendly, it comes with its own quirks. Here are a few issues you might run into when using YAML with Delphi:
1. Indentation Rules
- YAML is indentation-sensitive.
- Spaces only — tabs are not allowed for indentation.
- A single misplaced space can completely change the structure.
valid:
key1: value
key2: value
invalid:
key1: value
key1: value # wrong indentation
2. Duplicate Keys
Unlike JSON, YAML technically allows duplicate keys in mappings, but this can lead to unexpected behavior. YAML Parsers will typically keep only the last occurrence.
settings:
timeout: 10
timeout: 30 # overwrites the first one
VSoft.YAML has a parser option to control the handling of duplicate keys
options := TYAML.CreateParserOptions;
options.DuplicateKeyBehavior := TYAMLDuplicateKeyBehavior.dkError; // default is dkOverwrite
doc := TYAML.LoadFromFile(fileName, options);
Best practice: avoid duplicates in configs, and add validation in your app if needed.
3. Scalars and Quoting
YAML is permissive about quoting strings, which can sometimes surprise you:
path: C:\Temp\file.txt # might be misinterpreted due to backslashes
Safer to quote unusual strings:
path: "C:\Temp\file.txt"
4. Boolean Values
YAML recognizes a wide set of values as booleans: yes/no, true/false, on/off.
feature_enabled: yes # interpreted as boolean true
If you actually mean the literal string "yes", you must quote it:
feature_enabled: "yes"
5. Comments
While YAML supports # comments, they are not part of the data model and usually not preserved
VSoft.YAML does attempt to preserve comments. This is non standard. Generally, comments before mappings (objects) and sequences(arrays) are preserved, comments after scalar values may be preserved.
Blank lines will not be preserved.
6. Large or Complex Documents
- For deeply nested structures, readability can drop.
- Split configs into multiple YAML files if possible.
- Use
---(start) and ...(end) to separate documents in a single file if needed.
7. Type Guessing
By default, YAML interprets unquoted values:
42 → integer3.14 → float3.1.4 → stringtrue → boolean
If you want to enforce string semantics, quote the value:
port: "5432"
8. CRLF vs LF Line Endings
VSoft.YAML is tolerant of Windows vs Unix line endings, but if your configs are shared across systems, normalize line endings in your source control to avoid “it works on my machine” issues.
Conclusion
YAML offers developers a unique combination of human readability, expressiveness, and versatility. Unlike INI files, it can represent complex nested structures; unlike XML, it remains clean and concise; and unlike JSON, it's easier for humans to read and maintain.
The full list of features support by VSoft.YAML is available here.