Config files

SYNX itself is a permissive format. It holds game data, catalogues, prompt sets, reference examples; they need no naming discipline, because their vocabulary belongs to the subject: moveCost, atk, danceability are the language of the domain, not an author's sloppiness. The standard stays out of such files entirely.

Discipline is asked of config files only, for exactly one reason: every service's config means the same things. The cache address, the internal API secret, a session TTL, a bucket key — the same things across a dozen products. If one service calls it internal_api_secret, another internal_secret and a third auth.secret, the next person looks in the new service for what they already had, fails to find it, and invents a fourth name. A year later the configs can neither be compared nor moved.

So there are few rules here, and they are about one thing: the same thing is named the same way everywhere.

One platform value, one name

Checked by comparing configs against each other: if the same environment variable is read under different paths in different services, that is an error.

# in one service
redis
  url[required]:env REDIS_URL      # path: redis.url

# in another, the same thing spelled differently
redis_url[required]:env REDIS_URL  # path: redis_url — a divergence

The spelling already used by most services wins: renaming one is cheaper than renaming nine.

The key name

!active

port[type:int]:env:default:7001 PORT
refresh_ttl_sec[type:int] 900        # not refresh_ttl, not refresh_ttl_seconds
otp_length_count[type:int] 6         # a number always carries a unit
is_signup_open[type:bool] true       # a boolean carries a prefix
db_pool_max_count[type:int] 20       # "max" is not a unit by itself

• the key is snake_case;
• a number carries a unit: _ms _sec _min _hours _days _bytes _kb _mb _cents _pct _count _index;
• a boolean starts with is_ has_ can_ should_ was_ will_ must_;
• words that say nothing (data, info, value, result) are banned here as well.

The unit is spelled the way it is in code: _sec, not _seconds. Two spellings cost exactly as much as no unit at all.

Where the line runs

By filename: the files that actually configure a service (app.synx, values.synx, platform.synx) are listed explicitly. Running the rules across every file of the format in our repository produced 1091 findings, 1036 of which were quarrels with domain language — so the line is drawn by list, not by extension.

Comments

In a config a comment labels a section rather than restating a line, so the five-tag rule does not apply. This is the only exemption, and it is deliberate: # Server, # Redis, # Limits help you read the file and promise nothing about "why".