YINI — Frequently Asked Questions

A practical FAQ for YINI, a human-friendly configuration format designed to be structured, predictable, and easy to read.

If you’re new, you might want to start with Get Started.

Below, you will find questions and answers grouped into the following topics:

• Understanding YINI
• Structure & Syntax
• Readability & Formatting
• Data & Values
• Help & Next Steps

1. Understanding YINI

Q – What is a YINI config file?

YINI is a human-readable text format for representing structured information. It is designed to be clear, predictable, and easy for humans to read and write. It is suitable for configuration files, application settings, and general data-storage use cases.
The YINI format adds real structure: nested sections, lists (similar to JSON arrays), objects, and clear, predictable rules with comments allowed. It can be used to store app or service settings in files like config.yini.

Example (YINI):

^ App
name = "Demo"                       // This is a comment.
features = ["search", "dark-mode"]   # This is also a comment.

^^ Server                            # Define section "App.Server"
host = "0.0.0.0"
port = 8080

Q – What is the format of a YINI file?

YINI is the name of the configuration/data format itself. A YINI file is a plain-text file with human-readable syntax. It’s based on key-value pairs, section markers, and optional comments.

It supports:

• Sections with ^, ^^, etc. for nesting.
• Key-value pairs (settings) using = as key=value.
• Arrays [1, 2, 3] and objects { key: "value" }, etc.
• Comments with //, #, /* ... */.

Q – But, why exactly another config format like YINI?

YINI exists to offer a modern, structured, and predictable configuration format that feels familiar while avoiding common pitfalls in INI, YAML, and similar formats.

It focuses on three goals: readability, structure, and reliability:

• Familiar and readable – Uses key-value pairs like INI and keeps a familiar, readable layout, so it’s immediately understandable.
• Structured and nestable – Supports nested sections, lists, and objects cleanly, without indentation guessing or YAML-style ambiguity.
• Strict when you need it – Optional strict mode enforces spec-compliance for reliable configs in production environments.
• Relaxed when you don’t – Lenient mode lets you parse partial or loosely formatted files without breaking your workflow.
• Comment-friendly and human-first – Keeps support for ;, #, //, and even block comments (/* */) for maximum readability.
• Fully defined specification – Unlike traditional INI, YINI has an explicit, versioned grammar and spec, making it predictable across implementations.

Q – What is YINI based on or influenced by?

YINI is inspired by several well-known formats and languages, including INI, JSON, Python, and Markdown, along with a few familiar conventions from C-style languages. From INI it keeps the simple key/value structure, from JSON and Python it adopts clear and predictable data types, from Markdown it borrows a focus on readability, and from C-style languages it takes influence for features like line comments (//) and block comments (/* … */). Together, these ideas form a configuration format that is human-friendly, structured, and unambiguous — familiar to read, but much more capable than classic INI.

Q – Does YINI stand for YAML + INI?

No. The name YINI comes from Yet another INI, not YAML + INI.

The interpretation YAML + INI is understandable, but that is not where the name came from. YINI is inspired mainly by the simplicity of INI-style configuration files, while adding structured features such as nested sections, lists, inline objects, and strict/lenient parsing.

YINI can be compared with YAML as a configuration format, but it is not a YAML variant and does not try to be YAML-compatible.

Q – Why not just use INI/JSON/YAML/TOML?

Each of those formats works well, but each also has friction that shows up as configs grow:

• INI has no single universal standard for nested structure, lists, or typed values. In basic INI-style files, values tend to become loosely typed strings, and any structure beyond flat key-value pairs is up to convention.
• JSON has no comments, and its strict comma and quote rules can make hand-editing error-prone.
• YAML is powerful, but its significant whitespace and version/parser-dependent implicit typing can be surprising, such as no being parsed as false by YAML 1.1-style parsers.
• TOML is clear for flat and lightly nested configs, but its table syntax can get harder to follow once nesting goes a few levels deep.

YINI’s goal is to keep the parts of these formats that work, while removing some of the friction:

• INI-like simplicity — flat, readable syntax at a glance.
• Clear structure — real sections, lists, and objects, without relying on indentation to define nesting.
• Predictable rules — no implicit type coercion; strict mode is available when you want stricter validation.
• Comfortable to read and diff — changes stay easy to spot in version control.

YINI is not trying to replace INI, JSON, YAML, or TOML. If one of those already fits your project, use it.

YINI is here for when you want INI’s simplicity with fewer of its limits.

Q – What file extension should I use?

YINI documents use the .yini file extension.

Q – Is YINI production-ready?

Not quite yet — but it’s getting close:

• Specification: currently at v1.0 Release Candidate, meaning the syntax and structure are stable.
• Parser library: yini-parser-typescript (Node.js) is in beta, already implementing much (if not most) of the spec — see the Feature Checklist.
• CLI tool: yini-cli builds on the official parser for use in the terminal (validation, conversion, formatting).
• Suitable for experimentation and internal tools, though small breaking changes may still occur before the final 1.0 release.

Q – Will YINI remain stable over time?

Yes. The YINI specification follows semantic versioning, with stability as a core design goal.
Breaking changes are avoided whenever possible and are clearly documented in release notes when they do occur.

Parsers and tooling are supported by automated tests, with a long-term goal of maintaining 70–80% test coverage or higher.

Q – Why does YINI have both strict and lenient modes?

YINI defines one format, but parsers can apply the rules in either lenient or strict mode.

Lenient mode is the default. It is more forgiving for everyday editing and may tolerate recoverable issues, such as trailing commas in lists or inline objects, while still reporting diagnostics.

Strict mode is for stronger validation. A strict YINI document must follow additional rules, such as using exactly one explicit top-level section, ending with the /END document terminator, and using canonical syntax inside inline objects.

So the selected parser mode can affect whether a file is accepted. A file that works in lenient mode may need small changes before it is valid in strict mode.

This design keeps YINI approachable while still giving production systems and tooling a stricter validation path when correctness and predictability matter most.

Q – Who maintains YINI?

YINI is created and maintained by Marko K. Seppänen under the YINI-lang open-source organization.
The project follows a public specification, versioned releases, and transparent change tracking, ensuring long-term clarity and stability.

It’s an open-source project released under the Apache 2.0 license, with some sub-repositories published under the MIT license.

Q – What encoding should I use?

YINI files should be saved as UTF-8 without BOM for maximum compatibility.

Q – When is YINI a good choice?

YINI is a good fit when you want:

• Human-editable config files.
• Predictable parsing rules.
• Structured data without YAML complexity.
• Clear diffs in version control.

Q – Is YINI safe for untrusted input?

Parsers are designed to avoid code execution and unsafe evaluation.
However, treat configuration files as data — not executable input.

2. Structure and Syntax

Q – How do I define sections?

Each section starts with ^. Settings are grouped inside sections.

For ordinary section names, use a simple identifier such as App:

^ App
title = "AppName"

Here the text App is the section name.

If a section name needs spaces or special characters, write it as a backticked identifier:

^ `DB Config`
host = "localhost"

You can add more sections, for example:

^ App
title = "My App Title"
items = 25

^ Style
isDarkTheme = OFF

Q – How do I make another section inside a section?

To nest sections, add more carets (^) at the start of a line.

• ^ = section
• ^^ = sub-section
• ^^^ = sub-sub-section

Example:

    ^ App
      name = 'Demo'
      version = '1.0.0'

    ^ Database
      host = 'localhost'
      port = 5432

        // Add another caret `^` and you get a sub-section
        ^^ Credentials
           user = 'admin'
           password = "secret"

Q – Are tabs and whitespace important?

No (in the same sense as in Python or YAML).
In YINI, spaces and tabs don’t change meaning - indentation is just for human readability.

Q – Can YINI include or import other files?

No (not yet). YINI files are parsed independently.
Tooling may later support includes or imports as an optional extension.

Q – How does YINI handle duplicate keys or sections?

The YINI specification (1.0.0 RC 6) states that:

• In strict mode, duplicates are disallowed and will raise an error.
• In lenient mode, later duplicate keys or sections are ignored, the first entry wins, and the parser must report a warning diagnostic.

This means duplicates must not silently overwrite or merge existing entries.

Q – Does the order of keys or sections matter?

Usually, no: after parsing, the order of ordinary unique keys is not meant to change their value.

However, section headers are read in order because they define the current document structure and nesting. Order can also be observable when duplicate keys or sections appear in lenient mode, because the first entry wins and later duplicates are ignored with a warning.

3. Readability and Formatting

Q – Can I use comments alongside values?

Yes, various commenting styles are supported in YINI:

// This is a line comment

timeout = 30  // inline comment

#This is also a line comment

interval = 30  #inline comment

/* Block comment spanning
   multiple lines */

; Full-line comment (must be whole line).

Q – Is indentation required?

No. Indentation is purely for readability.
The hierarchy is defined only by the caret (^) section marker (and alternative section markers) — not by indentation.

4. Data and Values

Q – What value types are supported?

Common scalars and collections:

• Strings: (classic/raw/triple-quoted, per spec)
• Numbers: (ints, floats, exponential)
• Booleans: true/false, plus on/off and yes/no (all case-insensitive)
• Null: null (case-insensitive)
• Arrays: [1, 2, "str"]
• Objects: { host: "db", port: 5432 }

Q – Arrays and objects?

Yes and yes.

list = [1, 2, 3, 'four', true, null]

obj = { host: 'localhost', port: 5432 }

Q – Are strings required to be quoted?

Yes. Strings must be enclosed in single ' or double " quotes.
Triple-quoted strings are allowed for multi-line text.

Q – Are keys and section names case-sensitive?

Yes, keys and section names are case-sensitive. Keep a consistent style (e.g., lower_snake_case).
Note: However, keywords for null and booleans are not!

Q – Are booleans and null case-insensitive?

Yes, key words are case-insensitive.
true, True, ON, off, null, Null all parse the same.

Q – Are numeric values automatically typed?

Yes. Integers and floating-point numbers are automatically detected; you don’t need suffixes.

5. Help and Next Steps

Q – Is there a CLI for YINI?

Yes. Use npx yini-cli (requires Node.js installed) for parsing or validating files.

Q – Syntax highlighting for YINI config files?

Yes, check out https://github.com/YINI-lang/syntax-highlighting
The repository includes definitions in tmLanguage, that enable syntax highlighting in VSCode and any editor supporting TextMate grammars.

Didn’t find your answer?

• ➡️ Join the discussion on GitHub ↗
• ➡️ Get Started guide