Using YAML with Delphi - VSoft.YAML

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 → integer
• 3.14 → float
• 3.1.4 → string
• true → 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.