Nested vs Flat Key Conversion for Properties Files

Nested vs Flat Conversion

The tool offers two modes for converting properties keys to JSON: nested (dot-notation expansion) and flat (preserve keys as-is). Choosing the right mode depends on your use case.

Example Properties

app.name=MyApp
app.version=1.0.0
app.db.host=localhost
app.db.port=5432
app.db.name=mydb
app.features.auth=true
app.features.cache=true
app.features.rate-limit=false

Nested Mode Output

{
  "app": {
    "name": "MyApp",
    "version": "1.0.0",
    "db": {
      "host": "localhost",
      "port": 5432,
      "name": "mydb"
    },
    "features": {
      "auth": true,
      "cache": true,
      "rateLimit": false
    }
  }
}

Flat Mode Output

{
  "app.name": "MyApp",
  "app.version": "1.0.0",
  "app.db.host": "localhost",
  "app.db.port": "5432",
  "app.db.name": "mydb",
  "app.features.auth": "true",
  "app.features.cache": "true",
  "app.features.rate-limit": "false"
}

When to Use Each Mode

Use Nested When...	Use Flat When...
Migrating to YAML or TOML format	Preserving exact key names matters
Creating API configuration responses	Keys contain dots that aren't hierarchical
Integrating with JSON-based tools	Working with Gradle or Maven properties
Visualizing configuration hierarchy	Round-trip fidelity is required
Generating documentation	Keys may conflict when nested

Conflict Warning

Nested mode can cause issues when both app.db and app.db.host exist as separate properties—the first is overwritten by the second's parent object. Flat mode avoids this entirely.