Document when a spring.config.import value is relative and when it is fixed

[GrahamHannington]

Several days ago on Stack Overflow I asked the related question, "spring.config.import: relative file path with vs without file: prefix?". I've had no answer.

I'm raising this issue here not as a question, but as either a docs enhancement request or a bug report, depending on whether the Spring Boot developers characterize the difference in behavior (details below) as a feature or a bug.

I'd planned to wait for answers on Stack Overflow and then, depending on those answers, possibly raise an issue here. However (acknowledging this is my problem), I'm on a tight schedule: I'm writing the user documentation for a Spring Boot application, and I want to know whether/how to document using spring.config.import to refer to a relative file path without a file: prefix.

Difference in behavior

I've recently been caught out by the difference that the file: prefix makes to a relative file path for spring.config.import.

In practice, it seems to be the case that:

• With a file: prefix, a relative file path is relative to the current working directory
• Without a file: prefix, a relative file path is relative to the file that contains spring.config.import

For example, given the following current working directory (that is, where config is a child directory of the current working directory):

config/
  application.yaml
  application-import.yaml

(In case anyone's wondering: yes, I'm familiar with profiles, and typically prefer them to spring.config.import.)

In application.yaml, to import application-import.yaml, I can specify either:

spring:
  config:
    import: file:./config/application-import.yaml # relative to current working directory

or:

spring:
  config:
    import: ./application-import.yaml # relative to application.yaml

This issue: docs enhancement request or bug report

The nature of this issue depends on whether the Spring Boot developers characterize this difference in behavior as a feature (working by design) or a bug:

• Feature: this issue is a docs enhancement request. Please enhance the Spring Boot docs to mention this difference in behavior under the heading "Importing Additional Data".
• Bug: this issue is a bug report. Please fix it; that is, so that there is no difference in the behavior of spring.config.import for a relative file path with vs without the file: prefix.

Related Spring Boot docs

I've looked for, but not found, information in the Spring Boot docs about specifying the location of a configuration properties file (such as application-import.yaml) as a relative path in the file system with a file: prefix versus without a file: prefix. If I've missed it, please point me to it.

It occurred to me that the Spring Boot developers and docs writers might say, "In the context of spring.config.* properties, all references to file system paths should be explicitly prefixed by file:. We deliberately don't document the behavior without that prefix."

But then, I found this counterexample in the 2020 Spring blog post "Config file processing in Spring Boot 2.4":

Import definitions use URL-like syntax as their value. If your location doesn’t have a prefix, it’s considered to be a regular file or folder.

So, the Spring Boot developers have explicitly considered the behavior for locations without a prefix. But, there's no mention of the difference in behavior between specifying a relative file path with or without a file: prefix.

Related Spring Framework docs

The "underlying" Spring Framework docs topic "Core Technologies / Resources" contains related information about specifying a file path with or without a file: prefix, but, understandably in that relatively low-level context, it's fairly general. For example:

When such a location path does not have a prefix, the specific Resource type built from that path and used to load the bean definitions depends on and is appropriate to the specific application context.

"appropriate to the specific application context" makes sense in the context of those relatively low-level Spring Framework docs, but it isn't much help to a user of the "higher-level" Spring Boot spring.config.import property.

If this difference in behavior is a feature and not a bug, then, unless I'm missing something in the Spring Boot docs, I suggest that the Spring Boot docs description of spring.config.import ought to explicitly describe this particular "appropriate to the specific application context" behavior.

[wilkinsona]

In the interests of avoiding duplicated effort, I'm going to close this one for now in favor of the question on Stack Overflow. We can re-open it if the Q&A determines that a change to Spring Boot's code or documentation is needed.

[GrahamHannington]

@wilkinsona wrote:

I'm going to close this

Yep, fair enough.

I'll gratefully accept tips on what I should have done to improve my chances of a timely resolution (feature or bug?).

After reading the guidelines in the comments of a new issue, I decided that the correct approach was to initially characterize the issue as a question on Stack Overflow. Should I simply have been more patient, waited longer for an answer on Stack Overflow?

For now, I'm going to document this current difference in behavior for my app users, to spare them the surprise that I experienced.

[wilkinsona]

Should I simply have been more patient, waited longer for an answer on Stack Overflow?

Yes, I think so. 3 days isn't long for an unpaid "support" channel.

For now, I'm going to document this current difference in behavior for my app users, to spare them the surprise that I experienced.

I think that's your best option, particularly given that you say you're on a tight schedule. Even if a change is to be made in Spring Boot, it would not be released until the end of this month at the earliest.

From your recent comment on the Stack Overflow question, I note that you're using Spring Boot 3.1.12. Open source support for Spring Boot 3.1.x ended in June 2024 and commercial support ends in June 2025. To be eligible for open source support I'd recommend upgrading to at least Spring Boot 3.3.x and ideally 3.4.x. Alternatively, commercial support is available.

[wilkinsona]

Digging some more, I think we need to improve the documentation. The behavior that you have observed with 3.1.x remains in 3.3.x and later and is intended.

When spring.config.import is used in a configuration properties file, a value that does not begin with a "URL prefix" such as file: or classpath: and does not start with / is treated as relative. In your example, file:config/application.yaml is importing ./application-import.yaml. There's no URL prefix and it does not start with / so it's treated as relative and becomes file:config/application-import.yaml. Similarly, if classpath:example.yaml was the importer, the location of the import would be classpath:application-import.yaml.

There are tests for this behavior but the documentation seems to be lacking. We can use this issue to make some improvements.

[GrahamHannington]

@wilkinsona wrote:

The behavior ... is intended.

👍 Thank you so much for that unequivocal statement; that's very helpful, exactly the kind of response I'd hoped for.

I now feel better about documenting that behavior in my app's docs.