
# Config files

An application keeps its settings in `application.yml`, `application.yaml` or `application.properties` in `lib/resources/`. That folder is what Spring calls the *classpath*, and the `resources:` prefix points into it. For each active [profile](profiles.md), `application-{profile}.*` is read as well, and its values win over the plain file.

You declare nothing in `pubspec.yaml`. The generator embeds every file of `lib/resources/` into the generated code, so the files work the same on the Dart VM, in AOT executables, in Flutter and on the web. A file larger than 1 MB is not embedded (the build warns): ship it as a Flutter asset or as a file next to the program.

## Why

One file per application, plus one per profile, keeps the defaults in one place and the differences small. Files next to the program (`./application.yml`, `./config/`) let an operator change a setting of a server or a desktop app without a new build, and they win over the packaged ones, as in Spring Boot.

## Example

```text
lib/
  main.dart
  resources/
    application.yml               # always read
    application-dev.yml           # read with the dev profile
    application-prod.properties   # read with prod (the formats can be mixed)
    config/
      application.yml             # also packaged, wins over resources:/
```

The two formats say the same thing:

```yaml
# lib/resources/application.yml
spring:
  application:
    name: shop
shop:
  title: NEON Books
  url: http://localhost:8080
  max-basket-size: 20
```

```properties
# lib/resources/application.properties
spring.application.name=shop
shop.title=NEON Books
shop.url=http://localhost:8080
shop.max-basket-size=20
```

Use the one you prefer, or both. When one location has both, `.properties` wins over `.yml`, which wins over `.yaml`.

## The shapes of values

Both formats end up as the same flat list of keys and values.

| Shape | YAML | `.properties` |
|---|---|---|
| Nested keys | `shop:` / `  payment:` / `    provider: stripe` | `shop.payment.provider=stripe` |
| A list | `hosts:` / `  - eu.neon.books` / `  - us.neon.books`, or `hosts: [eu, us]` | `shop.hosts[0]=eu.neon.books`, or `shop.hosts=eu,us`, or `shop.hosts[]=eu, us` |
| A list of objects | `servers:` / `  - name: eu` / `    url: https://eu.neon.books` | `shop.servers[0].name=eu` |
| A map | `prices:` / `  book: 12` / `  e-book: 8` | `shop.prices.book=12` |
| A map key with dots | `"[X-Shop.Id]": neon` (quoted) | `shop.headers[X-Shop.Id]=neon` |
| An empty value | `banner:`, `motto: ~` or `null` | `shop.banner=` |

- A YAML list becomes indexed keys (`shop.hosts[0]`, `shop.hosts[1]`). The plain key `shop.hosts` is not set, so `@Value(r'${shop.hosts}')` finds nothing. Write a comma list (`hosts: eu,us`) for code that reads one key. Spring Boot behaves the same way.
- Indexes start at 0 and have no gaps.
- For a target that is not a `String`, an empty value counts as "not set", so the default applies.

## Several documents in one file

One file can hold several documents. YAML separates them with `---`; `.properties` with a line `#---` (or `!---`). A later document overrides an earlier one. A document can be limited to some profiles or to a cloud platform, so one file can carry the development values and the production overrides:

```yaml
shop:
  url: http://localhost:8080
---
spring:
  config:
    activate:
      on-profile: prod
shop:
  url: https://neon.books
```

```properties
shop.url=http://localhost:8080
#---
spring.config.activate.on-profile=prod
shop.url=https://neon.books
```

A `.properties` separator is the whole line: `#---` or `!---` at the start of the line, exactly three hyphens, nothing after them but spaces or tabs. It does not count right after a comment with the same prefix (leave a blank line, or use `!---`), nor where the line before continues with `\`. Put comments below the `on-profile` line, not right after the separator; Spring Boot joins such a document to the previous one, this loader does not.

See [Profiles](profiles.md#documents-for-some-profiles-or-platforms) for `on-profile` expressions and `on-cloud-platform`.

## Only in `.properties`

```properties
# The separator between key and value is =, : or whitespace.
shop.name=NEON
shop.city: Berlin
shop.country Germany

# A line ending in \ continues; the next line's leading spaces are dropped.
shop.welcome=Welcome to NEON Books, \
             the shop of books.

# Escapes: \t \n \r \f \uXXXX. In a key, \= \: and "\ " keep those characters.
shop.key\=with\:colon=yes

# A comment starts with # or ! at the start of the line; a # later is part of the value.
shop.color=#673AB7
```

- Files are read as **UTF-8**, so `Grüße` can be written as is. Spring Boot reads ISO-8859-1. A file that is not valid UTF-8 fails the start with a `ConfigDataLoadException` naming it. Name another encoding where the file is named: `resources:legacy.properties[encoding=iso-8859-1]` (UTF-8, ISO-8859-1 and US-ASCII are known, with Java's names and aliases such as `latin1`).
- When a key appears twice, the last value counts. Trailing spaces of a value are kept.

## Only in YAML

```yaml
# An anchor shares a block; the mapping's own keys win over the merged ones.
defaults: &defaults
  timeout: 5s
  retries: 3
shop:
  eu:
    <<: *defaults
    url: https://eu.neon.books
  us:
    <<: *defaults
    retries: 5
  color: '#673AB7'   # quoted: a # after a space starts a comment
```

YAML is read as YAML 1.2 (Spring Boot's SnakeYAML reads 1.1):

- `on`, `off`, `yes` and `no` stay strings; they still convert to `bool` where a `bool` is expected, and `off` works for an enum with an `off` constant (`spring.main.banner-mode: off`);
- `0777` is the number 777, not octal;
- a duplicate key or invalid YAML fails the start with its line and column.

## Where files are searched

The locations come in two groups. The second group overrides the first entirely:

| Group | Locations, lowest first | What they are |
|---|---|---|
| 1, packaged | `resources:/`, `resources:/config/` | `lib/resources/` and `lib/resources/config/`, embedded by the generator |
| 2, next to the program | `file:./`, `file:./config/`, `file:./config/*/` | The working directory, `./config/` and each subdirectory of it in alphabetical order |

So `./application.properties` next to a server binary wins over the packaged `application-prod.properties`. Within a group, later locations win, profile files win over plain ones, and the last active profile wins. Every default location is optional.

In tests (`springBootTest`), `test/resources/` comes before `lib/resources/`, so `test/resources/application-test.yml` is found, and a file there replaces a packaged file with the same path.

## Changing the search

These keys change which files are searched. They are read only from the sources that exist before the files are read: the command line, `--dart-define`, the environment, `SPRING_APPLICATION_JSON` and the default properties. A config file cannot set them.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.config.name` | comma list | `application` | The base names of the files. `application,shop` reads `application*.*` and `shop*.*`; a later name wins |
| `spring.config.location` | locations | the two groups above | Replaces the default locations. `,` separates groups; `;` joins locations into one group |
| `spring.config.additional-location` | locations | none | Groups searched after the locations, so they win over them |
| `spring.config.on-not-found` | `fail` / `ignore` | `fail` | `ignore` makes every location optional. Any other value fails the start |

```bash
# Only the packaged files and /etc/shop/, which wins.
dart run bin/main.dart --spring.config.location=optional:resources:/,file:/etc/shop/

# The usual locations, then one more file on top.
dart run bin/main.dart --spring.config.additional-location=file:./override.yml

# Read shop.yml instead of application.yml.
SPRING_CONFIG_NAME=shop dart run bin/main.dart
```

A location written here takes every form of [Imports](imports.md#location-forms): `optional:`, directories ending in `/`, wildcards, extension hints (`file:./conf[.yml]`), encoding hints, `configtree:`.

## Missing files

- A required file that does not exist fails the start: `Config data resource 'file [./override.yml]' via location 'file:./override.yml' does not exist`, with the action `prefix it with 'optional:'`.
- A required directory that does not exist, or a wildcard with no match, fails too.
- `optional:` makes one location optional; `spring.config.on-not-found=ignore` makes all of them optional.
- The profile variants searched by name (`application-dev.yml`) are always optional.
- A location counts as found when one of its profile variants is found, as in Spring Boot.

## Without SpringApplication

`ConfigDataEnvironment` is the class that does this work. A program on `spring_core_dart` alone, or a tool, runs it itself:

```dart
// Reads lib/resources/application.yml, ./application.properties, profiles and imports.
Future<void> main(List<String> args) async {
  final environment = StandardEnvironment()
    ..propertySources.addFirst(SimpleCommandLinePropertySource(args));
  await ConfigDataEnvironment(environment).processAndApply();
  print(environment.getProperty('shop.url'));
}
```

Its constructor takes a `resourceLoader` (for assets or files held in memory), `loaders` (the formats: `PropertiesPropertySourceLoader` and `YamlPropertySourceLoader` by default; a `PropertySourceLoader` of your own adds a format), `defaultLocations` and `additionalProfiles`. `processAndApplySync()` is the synchronous form.

## In Spring (Java)

The same file names, locations and rules as Spring Boot, except:

- `resources:` instead of `classpath:`, and no `resources*:` or wildcard search in config locations.
- `.properties` files are UTF-8; `PropertiesPropertySourceLoader(encoding: latin1)` gives Spring Boot's ISO-8859-1.
- YAML 1.2 instead of 1.1.
- No `application.xml`: `spring.config.import=x.xml` fails the start ("XML properties files are not supported").
- In a `;` group, spaces around an entry are trimmed and empty entries skipped.

## See also

- [Profiles](profiles.md)
- [Imports](imports.md)
- [Overview: which source wins](index.md)
- [The generator: resources](../../spring-core-dart-generator/resources.md)
- [Resources](../../spring-core-dart/resources/index.md)
