Configuration files

Configuration files often start out simple… and end up turning into a fragile mix of:

• data,
• implicit conventions,
• human comments,
• and “memorized” logic.

What kind of configurations

Common examples where STXT fits well:

• Application configuration (server, ports, flags, limits).
• Per-environment configuration (dev / staging / prod).
• Pipelines and jobs.
• Feature flags.
• Service configuration (timeouts, retries, endpoints).
• “Documented” configuration (long comments, context).

Common problems with other formats

In practice, teams run into:

• JSON:

  • Strict but not very human.
  • No real comments.
  • Hard to maintain as it grows.

• YAML:

  • More human, but fragile with indentation.
  • Too many equivalent ways to express the same thing.
  • Complex parsers and surprising behavior.

• INI / properties:

  • Flat, with no real hierarchy.
  • Implicit types and ad-hoc rules.

• XML:

  • Verbose.
  • Not very friendly for manual editing.

STXT aims for a different balance:

• Minimal syntax.
• Clear hierarchy via indentation.
• Literal text when needed.
• Optional validation, not mandatory.

Example 1 — Server configuration

Human-readable, hand-editable, and structured configuration.

Server Config (@com.acme.server):
	Name: api-gateway
	Environment: production

	Network:
		Host: 0.0.0.0
		Port: 8080
		Public url: https://api.acme.com

	Threads:
		Min: 8
		Max: 64

	Timeouts:
		Read ms: 5000
		Write ms: 5000

	Logging:
		Level: INFO
		Format: json

	Features:
		Feature:
			Name: experimental-cache
			Enabled: false
		Feature:
			Name: audit-logging
			Enabled: true

	Description >>
		Main configuration of the API gateway.
		This file is versioned in Git and deployed along
		with the application.

		Critical changes must go through review.

What STXT adds here

• Node names provide clear semantics.
• The hierarchy “shows” itself without thinking.
• Explanatory text lives alongside the configuration (Description >>).
• There are no magic keys or implicit structures.

Example 2 — Per-environment configuration

Same format, different environments, without duplicating structure.

Application Config (@com.acme.app):
	App name: Billing

	Environments:
		Environment:
			Name: dev
			Database:
				Url: jdbc:postgresql://localhost/dev
				Max connections: 5
			Debug: true

		Environment:
			Name: staging
			Database:
				Url: jdbc:postgresql://staging/db
				Max connections: 10
			Debug: false

		Environment:
			Name: prod
			Database:
				Url: jdbc:postgresql://prod/db
				Max connections: 30
			Debug: false

Advantages over “copy and paste”

• The structure is always the same.
• It’s easy to detect differences between environments with diff.
• You can validate that all environments have the same fields.

Example 3 — Feature flags

A classic case where data and explanatory text coexist.

Feature Flags (@com.acme.features):
	Feature:
		Key: new-checkout
		Enabled: false
		Owner: Payments
		Description >>
			New checkout flow.
			Enable progressively per environment.

	Feature:
		Key: rate-limit-v2
		Enabled: true
		Owner: Platform
		Description >>
			New rate limiting system.
			Replaces the previous version based on filters.

Validation with @stxt.template

In configuration it’s very common to want to:

• Avoid misspelled fields.
• Control types (numbers, booleans, dates).
• Restrict possible values (ENUM).

Template (@stxt.template): com.acme.server
	Description: API server configuration
	Structure >>
		Server Config:
			Name: (1)
			Environment: (1) ENUM [dev, staging, production]

			Network: (1)
				Host: (1)
				Port: (1) INTEGER
				Public url: (?)

			Threads: (?)
				Min: (1) NATURAL
				Max: (1) NATURAL

			Timeouts: (?)
				Read ms: (?) NATURAL
				Write ms: (?) NATURAL

			Logging: (?)
				Level: (1) ENUM [DEBUG, INFO, WARN, ERROR]
				Format: (?) ENUM [text, json]

			Features: (?)
				Feature: (*)
					Name: (1)
					Enabled: (1) BOOLEAN

			Description: (?) TEXT

This template:

• Prevents typos (Port vs Ports).
• Guarantees basic types.
• Keeps flexibility (many fields are still optional).

Validation with @stxt.schema

When configuration becomes a contract between systems:

• agents,
• external validators,
• automated deployments,

a schema provides full and explicit control.

In practice:

• The template is designed (more readable).
• It is compiled to a schema.
• The runtime validates against the schema.

Conceptual comparison

STXT for configuration sits between:

• JSON → too rigid and not very human.
• YAML → human but ambiguous.
• DSL languages → powerful, but dangerous.

STXT:

• Executes nothing.
• Evaluates no expressions.
• Includes no external files.

It only describes structure + data + text.

Usage recommendations

• Use stable and descriptive node names.
• Group by domains (Network, Logging, Features).
• Use ENUM for environments, levels, states.
• Document important decisions with >> blocks.
• Keep validation as an additional layer, not as an initial requirement.

Summary

Configuration files are a natural use case for STXT:

• Humans can read and modify them with confidence.
• Machines can validate and process them unambiguously.
• The format scales from “simple config” to strict contracts without changing languages.