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

🧠 The simple idea

Think of YINI as three familiar ideas combined:

INI → simple key = value
JSON → real types (arrays, objects, booleans, numbers)
Headings → clear structure markers (^, ^^, ^^^)

That's YINI — familiar, readable, and structured.

❓ 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 you can do with YINI

Use YINI in real projects — without changing your workflow.

🛠 Convert YINI → JSON with a simple CLI.
📦 Load YINI directly into your app as native objects.
🧩 Use it for configs, 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?

Many configuration formats become harder to maintain as projects grow.

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

YINI was designed to address these issues.

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

Get Started View Examples

⚖️ 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.

How YINI compares to other config formats

YINI supports both strict and lenient parsing modes, depending on how much enforcement you need.

Feature	YINI (strict)	YINI (mode)	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	✅	➖	❌	➖	❌	➖

Strict = safety & predictability · Lenient = flexibility & convenience

✅ Strong support · ➖ Partial / debated · ❌ Poor or not supported

Strict when it matters. Flexible when it helps.

YINI supports two parsing modes:

Strict mode enforces the full specification and fails fast on errors — ideal for production, CI, and validation.
Lenient mode prioritizes readability and resilience — useful during development, experimentation, or when parsing partial configs.

The format itself is fully defined by the YINI specification.
Strict vs lenient is a parser choice, not a change to the language — the same YINI file works in both modes.

This lets YINI stay human-friendly without sacrificing predictability when correctness matters.

⚡ Try YINI in under a minute

No build step. No setup required.

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

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.

View Examples View on GitHub ↗

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