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.

The questions and answers are grouped by topic.

• 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 storing organized data. It is designed to be clear, predictable, and easy for people to read and write. It is suitable for configuration files, application settings, and general data storage.

YINI supports nested sections, lists (similar to JSON arrays), inline objects, and comments. It can store app or service settings in files such as 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 the following features.

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

Q – Why create another configuration format?

YINI offers a modern, structured, and predictable configuration format that feels familiar while avoiding some common problems in INI, YAML, and similar formats.

It focuses on readability, structure, and reliability.

• Familiar and readable – Uses key-value pairs like INI and keeps a familiar, readable layout, so it’s immediately understandable.
• Clear nested structure – Supports nested sections, lists, and inline objects without using indentation to define structure.
• Strict when you need it – Optional strict mode checks additional rules when stronger validation is needed.
• Relaxed when you don’t – Lenient mode accepts some minor issues, such as trailing commas, and reports warnings when appropriate.
• Comment-friendly and human-first – Keeps support for ;, #, //, and even block comments (/* */) for maximum readability.
• Versioned specification – Unlike traditional INI, YINI has a written grammar and specification to help implementations behave consistently.

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 clear — familiar to read, but 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 can become more difficult to use as configuration files grow.

• INI has no single universal standard for nested structure, lists, or typed values. In basic INI-style files, values are often treated as strings, and each tool may handle more complex structures differently.
• JSON has no comments, and its strict comma and quote rules can make hand-editing error-prone.
• YAML is powerful, but indentation affects meaning, and automatic type conversion can vary by YAML version and parser. For example, YAML 1.1-style parsers may read no as false.
• 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 useful parts of these formats while avoiding some of their difficulties.

• 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 — values have clear syntax, and strict mode is available when you want stronger 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.

Files intended for strict validation may use .strict.yini, such as config.strict.yini. This suffix is only a naming convention. The parser, CLI, or application must still select strict mode.

Q – Is YINI production-ready?

Not yet. The current specification is YINI 1.0.0 RC 6, a release-candidate draft. Minor corrections and clarifications may still be made before the final 1.0.0 release.

The TypeScript/JavaScript parser is the primary parser implementation. The YINI CLI uses that parser for validation, inspection, and conversion. A Python parser is also available.

YINI can be useful for experiments and internal tools. Before using it in an important production system, review the current specification and parser status, and test it against your application’s requirements.

Q – Will YINI remain stable over time?

Stability is a core design goal. The YINI specification uses Semantic Versioning-style version numbers to show whether a release contains incompatible changes, new compatible features, or corrections.

YINI is still a release candidate, so changes remain possible before 1.0.0. Changes should be documented in the specification’s change log and project release notes.

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 accepts some minor issues, such as trailing commas in lists or inline objects, while still reporting warnings and errors.

Strict mode is for stronger validation. A strict YINI document must follow additional rules. For example, it must have exactly one top-level section, end with the /END document terminator, and use : between keys and values 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 everyday editing simple while giving applications and tools a stricter way to check files.

Q – Does @yini strict enable strict mode?

No. @yini strict declares that the document expects strict mode, but it does not change the parser mode. The parser API, CLI option, or application must select strict mode.

For example, use yini validate --strict config.yini with the YINI CLI.

Q – Who maintains YINI?

YINI is created and maintained by Marko K. Seppänen under the YINI-lang open-source organization.

The specification and release history are public, so changes can be reviewed.

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 the following.

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

Q – Is YINI safe for untrusted input?

YINI does not define expressions that execute code. However, an application must still treat parsed configuration as untrusted data. Validate values before using them, and apply suitable file-size and resource limits when accepting files from untrusted sources.

2. Structure and Syntax

Q – How do I define sections?

A section usually starts with ^, the recommended section marker. 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"

^^ Server
host = "localhost"
port = 8080

Here, Server is inside App. Indentation is optional; the two carets define the nesting.

Q – Is indentation (tabs and spaces) important?

Indentation does not define structure in YINI. You may use spaces or tabs to make a file easier to read. Section markers such as ^ and ^^ define the nesting.

Spaces and tabs are still required or forbidden in a few syntax rules. For example, a numeric section marker requires a space or tab before the section name: ^10 DeepSection.

Q – Can YINI include or import other files?

No. YINI files are parsed independently. The name @include is reserved for possible future use, but file inclusion is not defined in RC 6.

Q – Can keys or section names contain spaces or punctuation?

Yes. Use backticks when a name contains spaces, hyphens, periods, or other characters that are not allowed in a simple name:

^ `Database Settings`
`connection.timeout` = 30
`read-only` = true

Q – How does YINI handle duplicate keys or sections?

The following duplicate-handling rules apply in YINI 1.0.0 RC 6.

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

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 also matters 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, several comment 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).

It is best to use one comment style consistently within a file.

Q – Can I temporarily disable a line?

Yes. Put -- at the start of the line, after any indentation. The parser ignores the entire line:

timeout = 30
--timeout = 60

Disabled lines are useful while testing a configuration. Use comments for notes written for people.

4. Data and Values

Q – What value types are supported?

YINI supports these common single values and grouped values.

• Strings: single-quoted, double-quoted, and triple-quoted
• Numbers: integers, decimal numbers, and scientific notation
• Booleans: true/false, plus on/off and yes/no (all case-insensitive)
• Null: null (case-insensitive)
• Lists: [1, 2, "str"] (called arrays in JSON and many languages)
• Inline objects: { host: "db", port: 5432 }

Q – Does YINI support lists and inline objects?

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 – How do escape sequences work in strings?

Ordinary YINI strings are raw by default. A sequence such as \n remains a backslash followed by the letter n.

Use a string with a C or c prefix when escape sequences should be processed:

rawPath = "C:\Users\Robin"
message = C"First line\nSecond line"

In message, \n becomes a newline.

Q – Are keys and section names case-sensitive?

Yes, keys and section names are case-sensitive. Keep a consistent style, such as lower_snake_case. Boolean and null keywords are different: they are case-insensitive.

Q – Are booleans and null case-insensitive?

Yes, these keywords are case-insensitive.

true, True, ON, off, null, Null all parse the same.

Q – Are numeric values automatically typed?

Yes. Number literals are parsed as numbers based on their syntax. You do not need type names or suffixes.

Q – Does YINI expand environment variables?

No. Environment-variable expansion and string interpolation are not part of the YINI format. An application may add that behavior after parsing, but it should document its own rules clearly.

5. Help and Next Steps

Q – Is there a CLI for YINI?

Yes. With Node.js installed, use npx yini-cli parse config.yini to parse a file or npx yini-cli validate config.yini to validate it.

See the YINI CLI guide for installation and command examples.

Q – Which YINI parsers are available?

The official TypeScript/JavaScript parser is the primary implementation. An official Python parser is also available.

See the parser overview for examples and installation instructions.

Q – Can I try YINI without installing anything?

Yes. Use the YINI Playground in your browser to write and parse YINI examples.

Q – Is syntax highlighting available?

Yes. The YINI syntax-highlighting repository ↗ includes TextMate grammar definitions for Visual Studio Code and other editors that support TextMate grammars.

Didn’t find your answer?

• ➡️ Join the discussion on GitHub ↗