What is YINI and Why?

YINI is a human-friendly, text-based configuration format — less verbose than JSON, simpler than YAML, and more expressive than INI.

A calm, predictable way to write configuration and structured data for real-world projects.

Get Started View Examples

❓ What is YINI?

YINI is an INI-inspired, text-based data format designed for humans first.

It combines:

the simplicity of INI
the structure of JSON
the flexibility people want from YAML

Example of YINI code:

Source file: basic.yini

💡 What can I do with YINI?

Build, convert, and consume structured configuration and data with simple tools.

🛠 Convert YINI → JSON via CLI.
📦 Load YINI into your app as native objects.
🧩 Use YINI for configuration, data files, pipelines, and tooling.

🧭 Why should I care?

Because configuration lives for years, not minutes. YINI is designed to stay readable, predictable, and safe as projects grow.

🧯 Why does YINI exist?

Most config formats fail as projects grow.

INI becomes flat and unstructured
JSON becomes noisy and hard to edit
YAML becomes fragile and unpredictable

YINI was created to fix that.

✨ What makes YINI different?

Clear structure without indentation rules
No fragile whitespace semantics.
Readable nesting that scales
Files remain easy to scan even when large.
Predictable parsing
Defined by a formal grammar and spec.
Human-first design
Comments, consistency, minimal noise.
Balanced design
More structure than INI, less noise than JSON, fewer edge cases than YAML.

⚖️ Quick comparison

JSON (harder to read & maintain at scale) vs YINI

JSON:

{
  "service": {
    "id": "aurora-gateway",
    "environment": "prod",
    "telemetry": {
      "samplingRate": 0.15,
      "exporter": "otlp",
      "endpoint": "http://otel-collector:4317"
    },
    "http": {
      "listen": "0.0.0.0",
      "port": 9000,
      "trustedProxies": ["10.0.0.0/8", "192.168.0.0/16"]
    },
    "limits": {
      "requestsPerMinute": 1200,
      "burst": 60,
      "maxBodyKb": 512
    },
    "webhooks": {
      "enabled": true,
      "targets": [
        {
          "name": "alerts",
          "url": "https://hooks.example.com/alerts",
          "secret": "****"
        },
        {
          "name": "billing",
          "url": "https://hooks.example.com/billing",
          "secret": "****"
        }
      ]
    },
    "_comment": "JSON can't do comments; people add fields like this (or separate docs)."
  }
}

YINI keeps the config readable and self-documented (real comments), with clear structure without the JSON noise. And large JSON can be annoying to maintain.

YINI (same config, cleaner + real comments):

/* Aurora Gateway service configuration (human-edited) */

^ Service
id          = "aurora-gateway"
environment = "prod"

^^ Telemetry
samplingRate = 0.15          // 0.0 - 1.0
exporter     = "otlp"
endpoint     = "http://otel-collector:4317"

^^ Http
listen         = "0.0.0.0"
port           = 9000
trustedProxies = ["10.0.0.0/8", "192.168.0.0/16"]

^^ Limits
requestsPerMinute = 1200
burst             = 60
maxBodyKb         = 512

^^ Webhooks
enabled = true

targets = [
  { name: "alerts",  url: "https://hooks.example.com/alerts",  secret: "****" },
  { name: "billing", url: "https://hooks.example.com/billing", secret: "****" }
]

"YAML foot-gun" vs YINI predictability (tabs/indentation)

YAML:

# One stray indent changes the structure
app:
  name: My App
  server:
    host: 127.0.0.1
    port: 8080
   allowedOrigins:   # <- off by one indent (hard to spot)
    - https://myapp.com
    - "http://localhost:3000"

YAML uses indentation to define structure; YINI uses explicit section markers. This makes large configs easier to scan — and much harder to break accidentally.

YINI (same config):

# Structure is defined by markers; indentation is optional
^ App
name = "My App"

^^ Server
host = "127.0.0.1"
port = 8080
allowedOrigins = ["https://myapp.com", "http://localhost:3000"]

Point: In YINI the hierarchy is signaled by markers, not whitespace.

Quick comparison table

Feature	YINI	INI	JSON	YAML	TOML
Human-friendly by default	✅	➖	❌	✅	➖
Readability at scale	✅	❌	❌	➖	➖
Predictable parsing	✅	❌	✅	❌	✅
Formal grammar / spec	✅	❌	✅	❌	✅
Nested structure	✅	➖	✅	✅	✅
Comments	✅	✅	❌	✅	✅
Minimal syntax noise	✅	✅	❌	➖	➖
Designed for configuration	✅	✅	➖	✅	✅
Clear error diagnostics	✅	❌	✅	❌	✅
Safe for large configs	✅	❌	➖	❌	➖

⚡ Try YINI in under a minute

No build step. No installation. No setup.

Save the two lines below as config.yini:
```
^ App
name = "Hello"
```
From your terminal, run this:
```
npx yini-cli parse --pretty config.yini
```

Results in JSON:

{
    "App": {
        "name": "Hello"
    }
}

That's it.

You just parsed your first YINI file.

🧪 Real example

YINI code:

Source file: settings.yini

This example uses features from the official YINI specification.

Parsed output (JSON):

{
    "Settings": {
        "serviceId": "NebulaService",
        "release": "3.2.1",
        "debugMode": false,
        "tagline": ""Nebula" is a cloud of gas and dust in outer space.",
        "Network": {
            "bindAddress": "127.0.0.1",
            "bindPort": 8080,
            "allowedOrigins": [
                "https://myapp.com",
                "http://localhost:3000"
            ]
        },
        "Capabilities": {
            "enableSearch": true,
            "experimental": [
                "new-ui",
                "streaming-api"
            ],
            "pools": {
                "min_units": 2,
                "max_units": 5,
                "size_mb": 128,
                "timeout_sec": 90
            }
        },
        "DB Config": {
            "host": "db.internal",
            "ssl": true,
            "Security": {
                "username": "service_user",
                "password": "****"
            }
        }
    }
}

New to YINI? Read a short learn the YINI format.

🔭 Next steps

Get Started

Learn how to install and parse your first config in minutes.
Code Examples

Real-world YINI examples showing common configuration patterns.
Specification

Official YINI format rules with full technical details of the YINI format.
YINI on GitHub ↗
Official GitHub page.

YINI is open-source and actively maintained.