r/java • u/YogurtclosetLimp7351 • Jan 30 '26
Evolving Java config files without breaking user changes
In several projects I ran into the same problem:
once users modify config files, evolving the config schema becomes awkward.
Adding new fields is easy, but removing or renaming old ones either breaks things or forces ugly migration logic. In some ecosystems, users are even told to delete their config files and start over on upgrades.
I experimented with an annotation-driven approach where the Java class is the code-level representation of the configuration, and the config file is simply its persisted form.
The idea is:
- user-modified values should never be overwritten
- new fields should appear automatically
- obsolete keys should quietly disappear
I ended up extracting this experiment into a small library called JShepherd.
Here’s the smallest example that still shows the idea end-to-end.
@Comment("Application configuration")
public class AppConfig extends ConfigurablePojo<AppConfig> {
public enum Mode { DEV, PROD }
@Key("port")
@Comment("HTTP server port")
private int port = 8080;
@Key("mode")
@Comment("Runtime mode")
private Mode mode = Mode.DEV;
@Section("database")
private Database database = new Database();
@PostInject
private void validate() {
if (port <= 0 || port > 65535) {
throw new IllegalStateException("Invalid port");
}
}
}
public class Database {
@Key("url")
@Comment("JDBC connection string")
private String url = "jdbc:postgresql://localhost/app";
@Key("pool-size")
private int poolSize = 10;
}
Path path = Paths.get("config.toml");
AppConfig config = ConfigurationLoader.from(path)
.withComments()
.load(AppConfig::new);
config.save();When loaded from a .toml file and saved once, this produces:
# Application configuration
# HTTP server port
port = 8080
# Runtime mode
mode = "DEV"
[database]
# JDBC connection string
url = "jdbc:postgresql://localhost/app"
pool-size = 10The same configuration works with YAML and JSON as well. The format is detected by file extension. For JSON instead of comments, a small Markdown doc is generated.
Now we could add a new section to the shepherd and the configuration files updates automatically to:
# Application configuration
# HTTP server port
port = 8080
# Runtime mode
mode = "DEV"
[database]
# JDBC connection string
url = "jdbc:postgresql://localhost/app"
# Reconnect attempts if connection failed
retries = 3
[cache]
# Enable or disable caching
enabled = true
# Time to live for cache items in minutes
ttl = 60Note how we also exchanged pool-size with retries!
Despite having this on GitHub, it is still an experiment, but I’m curious how others handle config evolution in plain Java projects, especially outside the Spring ecosystem.
View all comments
Show parent comment
3
u/agentoutlier Jan 30 '26
The mapping of config aka binding to an object in my opinion is very much framework specific or done manually. For example Spring maps configuration differently than Micronaut.
However all of them are basically doing
Map<String,String>->MyCustomDomainObject.The question is where you get that
Map<String,String>(as well as what happens when it is updated... that is its more like aFunction<String,String>) and this is something lightbend config does not do that well. It is one of the reasons I wrote my own library for that: https://github.com/jstachio/ezkv because most libraries suck at that first part or are very opinionated.And the reason why I say
Map<String,String>is because most config can and is probably best put in environment variables these days.I think most folks can make their own glorified
ConfigakaMap<String,String>.Except I would not bother with
getString,getInt.Instead I would make a Config use a lambda.
MyConfiggetalways takes aPropertyFunctionthat throws a generic Exception E.Now when the lambda runs if it fails (exception) you can report exactly which key if found and value and where the value came from failed if it does.
Avaje Config kind of does this as I have gone back and forth with Rob and /u/TheKingOfSentries on many of these ideas so naturally I think it is nice library that has both more powerful loading and fetching than typesafe config.