YINI — Frequently Asked Questions

A quick, practical FAQ for the YINI configuration format.
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 an YINI config file?

A YINI config file is a human-friendly configuration file (like INI) that adds real structure: nested sections, 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 an YINI file?

YINI is the name of the markup 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 // or #, etc.

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

YINI was created to offer a modern, structured, and readable configuration language that feels familiar — yet while addressing some of the historical limitations found in INI and YAML.

It aims to combine simplicity, structure, and safety:

• Familiar and readable – Uses indentation and key-value pairs like INI, so it’s immediately understandable.
• Structured and nestable – Supports nested sections, lists, and objects cleanly, without indentation guessing or syntax 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 – Why not just use INI/JSON/YAML/TOML?

Use whatever suits your project best. YINI aims to:

• Keep INI-like simplicity.
• Add clear structure (sections, arrays, objects).
• Keep predictable rules (strict mode available).
• Be comfortable to read and diff.

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 – Who maintains YINI?

YINI is created and maintained by Marko K. Seppänen and the YINI-lang organization. It’s an open-source project released under the Apache 2.0 license.

Q – What encoding should I use?

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

2. Structure and Syntax

Q – How do I define sections?

Each section starts with ^. (Settings are grouped in sections.)

Start a section with ^ and then a name without spaces, e.g.:

^ App
title = "AppName"

Here the text “App” is the section name.

One 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, at least). 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 RC.3) states that:

• In strict mode, duplicates are disallowed and will raise an error.
• In lenient mode, duplicates are also not allowed — they may trigger a warning, but must not overwrite existing entries.

However, in the official YINI-lib yini-parser (Node.js), the behavior for handling duplicates in lenient mode is customizable.

Q – Does the order of keys or sections matter?

No, order may be preserved for readability but has no semantic meaning.

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 (must have a space after #)

interval = 30  # inline comment (must have a space after #)

/* 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, key words 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/yini-syntax
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