[[configuration-format]]
# Configuration Format
This section describes the configuration structure that is used by Spring initializr.
The metadata provided through configuration are driving the options exposed by a
particular instance and <<metadata-format.adoc#metadata-format,the project metadata
format>>.

The configuration is split in several sections:

* An `env` section used to provide various global settings.
* A `dependencies` section lists the available dependencies. This is the most
important section of the service as it defines the "libraries" that the user can
choose.
* The `groupId`, `artifactId`, `version`, `name`, `description` and `packageName`
provide default values for these project settings.
* The `types`, `packagings`, `javaVersions`, `languages` and `bootVersions` provide
the list of available option for each setting and which one is the default.



## Env section
TIP: Check {sc-initializr-generator}/metadata/InitializrConfiguration.java#L142[the code]
for a full list of the available configuration options.

The `env` element defines environment option that the service uses:

* `artifactRepository`: the URL of the (maven) repository that should be used to
download the Spring Boot CLI distribution bundle. This is only used by the `/spring`
endpoint at the moment.
* `springBootMetadataUrl` the URL of the resource that provides the list of available
Spring Boot versions.
* `forceSsl`: a boolean flag that determines if we should redirect browser to `https` when
browsing via `http`. Also force the use of `https` in all links. This is not enabled by
default to ease local use case but should be enabled in production.
* `fallbackApplicationName`: the name of the _default_ application. Application names
are generated based on the project's name. However, some user input may result in an
invalid identifier for a Java class name for instance.
* `invalidApplicationNames`: a fixed list of invalid application names. If a project
generation uses one of these names, the fallback is used instead.
* `invalidPackageNames`: a fixed list of invalid package names. If a project
generation uses one of these names, the default is used instead.
* `googleAnalyticsTrackingCode`: the Google Analytics code to use. If this is set,
Google analytics is automatically enabled.
* `kotlin`: kotlin-specific settings. For now, only the kotlin version to use can be
configured and is a mandatory option if Kotlin is enabled.
* `maven`: maven-specified settings. A custom maven parent POM can be defined and
whether or not the `spring-boot-dependencies` BOM should be automatically added to
the project.

If some of your dependencies require a custom Bill of Materials (BOM) and/or a custom
repository, you can add them here and use the id as a reference. For instance, let's
say that you want to integrate with library `foo` and it requires a `foo-bom` and a
`foo-repo`. You can configure things as follows:

```yml
initializr:
  env:
    boms:
      foo-bom:
        groupId: com.example
        artifactId: foo-bom
        version: 1.2.3
    repositories:
      foo-repo:
        name: foo-release-repo
        url: https://repo.example.com/foo
        snapshotsEnabled: false
```

You can then use the `foo-bom` and `foo-repo` in a "dependency" or "dependency group"
section.

NOTE: The `spring-milestones` and `spring-snapshots` repositories are available by
default. Please note that these are just references and won't impact the project
unless you choose a dependency that explicitly refer to a bom and/or repo by id.
Check the example below for more details.

## Dependencies section

The `dependencies` section allows you define a list of groups, each group having one
more `dependency`. A group gather dependencies that share a common characteristics
(i.e. all web-related dependencies for instance).

A `dependency` has the following basic characteristics:

* A mandatory identifier. If no further information is provided, a Spring Boot starer
with that id is assumed.
* A `name` and `description` used in the generated meta-data and the web ui.
* A `groupId` and `artifactId` to define the coordinates of the dependency.
* A `version` if Spring Boot does not already provide a dependency management for
that dependency.
* A `scope` (can be `compile`, `runtime`, `provided` or `test`).
* The reference to a `bom` or a `repository` that must be added to the project once
that dependency is added.
* A `compatibilityRange` used to determine the platform versions that are compatible
with the dependency.
* Links to resources such as a guide or a reference doc section.

TIP: Check {sc-initializr-generator}/metadata/Dependency.java[the code] for a full
list of the available configuration options.

Here is the most basic dependency entry you could have

[source,yaml,indent=0]
----
	initializr:
	  dependencies:
	    - name: Core
	      content:
	        - id: security
	          name: Security
	          description: Secure your application via spring-security
----

TIP: The `security` dependency is held within a group called "Core".

This adds an option name `Security` with a tooltip showing the description above. If
a project is generated with that dependency, the
`org.springframework.boot:spring-boot-starter-security` dependency will be added to
the project.

Let's now add a custom dependency that is not managed by Spring Boot and that only
work from Spring Boot `1.2.0.RELEASE` and onwards but should not be used in the 1.3
lines and further for some reason.

[source,yaml,indent=0]
----
	initializr:
	  dependencies:
	    - name: Core
	      content:
	        - id: my-lib-id
	          name: My lib
	          description: Secure your application via spring-security
	          groupId: com.example.foo
	          artifactId: foo-core
	          bom: foo-bom
	          repository: foo-repo
	          compatibilityRange: "[1.2.0.RELEASE,1.3.0.M1)"
----

If one selects this entry, the `com.example.foo:foo-core}` dependency will be added
and the Bill of Materials and repository for `foo` will be added automatically to
the project as well (see the "Env section" above for a reference to those
identifiers). Because the bom provides a dependency management for `foo-core` there
is no need to hard code the version in the configuration.

The `compatibilityRange` syntax follows some simple rules: a square bracket "[" or "]"
denotes an inclusive end of the range and a round bracket "(" or ")" denotes an
exclusive end of the range. A range can also be unbounded by defining a a single
version. In the example above, the dependency will be available as from
`1.2.0.RELEASE` up to, not included, `1.3.0.M1` (which is the first milestone of the
1.3 line).

### Dependency group

A dependency group gather a set of dependencies as well as some common settings:
`bom`, `repository` and `compatibilityRange`. If one of them is set, it is applied for all
dependencies within that group. It is still possible to override a particular value
at the dependency level.

## Other sections

The other section defines the default and the list of available options in the web
UI. This also drives how the meta-data for your instance are generated and tooling
support is meant to react to that.

For instance, if you want your groupId to default to `org.acme` and the
`javaVersions` to only be `1.8` and `11` you would write the following config:

[source,yaml,indent=0]
----
	initializr:
	  groupId:
	    value: org.acme
	  javaVersions:
	    - id: 11
	      default: false
	    - id: 1.8
	      default: true
----
