configuration-properties-profiles-kotlin-safe

name	configuration-properties-profiles-kotlin-safe
description	Design and diagnose Spring configuration, profiles, and `@ConfigurationProperties` binding for Kotlin applications. Use when property binding fails, environment-specific overrides behave unexpectedly, profile layering is confusing, secrets or defaults are modeled unsafely, or Kotlin nullability and constructor binding semantics make configuration errors hard to detect.

Configuration Properties Profiles Kotlin Safe

Source mapping: Tier 2 high-value skill derived from Kotlin_Spring_Developer_Pipeline.md (SK-16).

Mission

Make configuration predictable across local, test, staging, and production environments. Treat configuration as typed application input, not as unstructured text.

Read First

• application.yml, application.properties, and profile-specific files.
• @ConfigurationProperties classes and how they are registered.
• Environment variable names, Helm values, Config Server or Vault usage, and test overrides.
• Active profile configuration and profile groups.
• Any custom converters, property placeholders, or late-bound secret conventions.

Diagnose In This Order

1. Verify source precedence:
   • default config file
   • profile-specific file
   • environment variables
   • SPRING_APPLICATION_JSON
   • external config systems
2. Verify prefix mapping and key shape.
3. Verify constructor binding, defaults, and nullability.
4. Verify collection, map, nested object, duration, and data-size binding.
5. Verify profile activation and profile merge behavior.
6. Verify whether the bug exists only in tests or only in deployment templates.

Kotlin-Safe Modeling Rules

• Model genuinely required properties as required constructor parameters or validated fields.
• Use defaults only when the default is semantically safe, not merely convenient.
• Use nullable only when the application can handle absence explicitly.
• Keep properties classes small and focused by feature or external dependency.
• Prefer type-safe wrappers such as Duration, URI, or enums when they clarify the contract.

Advanced Configuration Traps

• Profile files merge; they do not behave like full replacement documents. Partial overrides can leave stale sibling values in place.
• Empty string is not the same as missing value. Many runtime failures come from "configured but blank" secrets.
• Nested objects can be partially bound, which may produce a shape that looks non-null but is still semantically invalid.
• Environment-variable translation from kebab-case to uppercase underscore is easy to misread, especially for nested maps and lists.
• ignoreUnknownFields or overly permissive binding can hide deployment drift.
• A property that fails only in one environment may really be a templating or secret-injection problem, not a Spring binding problem.
• Test overrides can mask missing production defaults if tests define properties more generously than runtime.
• Dynamic refresh or cloud config introduces lifecycle questions: startup validation alone may not be enough if config can change after boot.

Spring Config Data Nuances

• spring.config.import, profile groups, and spring.config.activate.on-profile can reshape the final config graph in ways that are not obvious from file names alone.
• List replacement and map merge behavior differ. A partial override may replace a whole list while only merging a map subtree.
• Placeholder resolution timing matters. A property can appear bound yet still fail later if it depends on an unavailable placeholder or secret source.
• Deprecating or renaming configuration keys is a migration problem. If compatibility matters, plan aliases or a staged rollout instead of a hard rename.
• Overusing @Profile on beans can make environment behavior harder to reason about than using one typed configuration model with feature flags or explicit toggles.

Expert Heuristics

• Prefer one typed configuration class per external dependency or feature slice. Giant omnibus config classes become impossible to validate and evolve safely.
• When the same property is set in several layers, document the intended owner. Hidden "last writer wins" behavior becomes operational debt fast.
• If a config issue appears only after deploy, compare rendered manifests or effective environment variables before editing Kotlin classes.
• If startup must fail on bad config, prove that with a test or smoke check. Teams often think they fail fast when they actually fail on first traffic.

Design Rules

• Validate required configuration at startup whenever possible.
• Keep secrets out of committed config examples unless obviously fake and explicitly marked.
• Model profile intent explicitly: local developer convenience, test isolation, operational environments, and feature toggles are different concerns.
• Prefer one source of truth for a property family. Duplicated definitions across profiles create drift fast.

Output Contract

Return these sections:

• Binding model: how the properties should be represented in Kotlin.
• Source precedence: where the effective value should come from.
• Root cause: exact mismatch in key, type, profile, or source.
• Minimal fix: the smallest safe file, code, or env change.
• Startup validation: what must fail fast at boot.
• Verification: how to prove the resolved config in the target environment.

Guardrails

• Do not hardcode secrets.
• Do not default required credentials to empty strings.
• Do not use nullable everywhere just to make the binder happy.
• Do not assume profile-specific files replace base config wholesale.
• Do not fix a binding symptom while ignoring the underlying precedence or environment problem.

Quality Bar

A good run of this skill leaves the configuration model easier to reason about across environments. A bad run "fixes" one YAML key while leaving nullability, precedence, and startup validation ambiguous.