YINI — Frequently Asked Questions

A quick, practical FAQ for the YINI data format (a human-readable text 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 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, 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 //, #, /* ... */.

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

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

It aims to combine simplicity, structure, and safety:

• 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 – 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.

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 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/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