Externalized configuration order different from the documented one

[kingan379]

According to documentation (https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config) config data such as application.properties files (point 3) has precedence over OS environment variables (point 5).

Now, In a spring application using Spring Boot 3.0.4 version, where I have:

1. application.properties with the content:
   myself.test=random_value_from_properties

2. Spring bean containing field with following annotation

@Value(${myself.test})
private String someVariable;

When I run this application, I can see that the someVariable value is 'random_value_from_properties' as expected. However, when I set the environment variable MYSELF_TEST to value 'random_value_from_os_env_var' and run the application again, the value of 'someVariable' is set to 'random_value_from_os_env_var'.

It means that the OS environment variables have precedence over application.properties, which is not what the documentation says. Interestingly, the spring boot 2.x documentation claimed different order (https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/boot-features-external-config.html), which would explain the behaviour. So either documentation is not correct, or the behaviour is not correct.

[wilkinsona]

The documentation says "Later property sources can override the values defined in earlier ones. Sources are considered in the following order:". The third item in the list is "Config data (such as application.properties files)" and the fifth item is "OS environment variables". OS environment variables are listed later than application.properties so OS environment variables are correctly documented as overriding application.properties. Note that, in 2.4.x, the order of the list was reversed and the explanation that proceeds it was updated as part of #22521.

[kingan379]

I understand, but are the rules of overriding described anywhere? I see sentences "Spring Boot uses a very particular PropertySource order" and "Later property sources can override the values defined in earlier ones," but I don't see any documentation about when the overriding happens (especially when using all default configuration). I totally understand that you may not see it as a bug, but it would be helpful to have it documented, because it may surprise many developers.

[wilkinsona]

Sorry, I don't understand what you'd like us to document. The documentation already lists the ordering of the property sources, and explains that the properties from entries later in the list overriding properties from entries earlier in the list. The exact details of this overriding are down to the ordering of the PropertySources that are added to the Environment and the behavior of its getProperty methods but this is really an implementation detail and, in my opinion, too low-level to warrant an explanation in the reference documentation.