Fork me on GitHub

Validating Micronaut configuration

The Micronaut Maven Plugin can validate your application’s configuration files (for example application.yml) using JSON Schema. The build fails when validation reports errors.

Goals

  • mn:validate-dev-configuration

    • Validates using the dev environment.

    • This goal is automatically executed by mn:run.

  • mn:validate-configuration

    • Intended for mvn package (for example production configuration).

    • Default environments: none.

  • mn:validate-test-configuration

    • Intended for mvn test.

    • Default environments: test.

Binding to the lifecycle

Configuration validation runs automatically when using Micronaut packaging types (jar, native-image, docker, docker-native, docker-crac):

  • validate-configuration runs during the prepare-package phase (before mvn package)

  • validate-test-configuration runs during the test phase (as part of mvn test)

  • validate-dev-configuration is automatically executed by mn:run

If you are not using Micronaut packaging or want to customize the phase bindings, you can configure explicit executions:

<plugin>
    <groupId>io.micronaut.maven</groupId>
    <artifactId>micronaut-maven-plugin</artifactId>
    <version>${micronaut-maven-plugin.version}</version>

    <executions>
        <execution>
            <id>validate-config</id>
            <goals>
                <goal>validate-configuration</goal>
            </goals>
            <phase>prepare-package</phase> <!-- optional: customize phase -->
        </execution>
        <execution>
            <id>validate-test-config</id>
            <goals>
                <goal>validate-test-configuration</goal>
            </goals>
            <phase>test</phase> <!-- optional: customize phase -->
        </execution>
    </executions>
</plugin>

Configuration

The mojos share a configurationValidation block and expose options equivalent to the validator CLI.

<plugin>
    <groupId>io.micronaut.maven</groupId>
    <artifactId>micronaut-maven-plugin</artifactId>

    <configuration>
        <configurationValidation>
            <enabled>true</enabled>

            <!-- CLI options -->
            <suppressions>
                <suppression>.*\.password</suppression>
            </suppressions>
            <suppressInjectErrors>
                <suppressInjectError>com.example.internal.*</suppressInjectError>
            </suppressInjectErrors>
            <failOnNotPresent>true</failOnNotPresent>
            <deduceEnvironments>false</deduceEnvironments>
            <validateDependencyInjection>false</validateDependencyInjection>
            <format>both</format> <!-- json|html|both -->
            <outputDirectory>${project.build.directory}/micronaut/config-validation</outputDirectory>

            <!-- Per-scenario overrides -->
            <dev>
                <environments>
                    <environment>dev</environment>
                </environments>
            </dev>
            <packageValidation>
                <environments>
                    <environment>prod</environment>
                </environments>
            </packageValidation>
            <test>
                <!-- additional environments are appended; 'test' is enabled by default -->
                <environments>
                    <environment>ci</environment>
                </environments>
            </test>
        </configurationValidation>
    </configuration>
</plugin>

Classpath configuration

Each scenario can be configured independently via:

  • classpathElements: replaces the default classpath used by the validator

  • additionalClasspathElements: entries appended to the default classpath

Dependency injection validation

By default, configuration validation checks configuration keys and values only. You can also validate Micronaut dependency injection wiring (missing beans, unsatisfied injections, etc.) by enabling:

<configurationValidation>
    <validateDependencyInjection>true</validateDependencyInjection>
</configurationValidation>

When enabled, dependency-injection issues are included in the generated reports and cause the build to fail.

If you need to suppress known dependency-injection issues (for example optional integrations in test fixtures), use suppressInjectErrors:

<configurationValidation>
    <validateDependencyInjection>true</validateDependencyInjection>
    <suppressInjectErrors>
        <suppressInjectError>com.example.optional.MissingBean</suppressInjectError>
        <suppressInjectError>com.example.experimental.*</suppressInjectError>
    </suppressInjectErrors>
</configurationValidation>

suppressInjectError supports exact class names and * wildcard patterns.

Reports

Reports are written under ${project.build.directory}/micronaut/config-validation/<scenario> by default. Depending on format, the plugin generates:

  • configuration-errors.json

  • configuration-errors.html

Caching

Validation results are cached on disk to avoid re-running on every build. By default, validation re-runs when src/main/resources changes. When validateDependencyInjection is enabled, classpath entry metadata/content is also fingerprinted for cache invalidation.

Disable caching with:

<configurationValidation>
    <cacheEnabled>false</cacheEnabled>
</configurationValidation>