Spring Boot Config JSON Schema Generator

Alex Mondshain <alex.mondshain@gmail.com> 2014-09-09

A Spring Boot starter that generates JSON Schema documentation from your application’s @ConfigurationProperties classes and Spring Boot configuration metadata. The generated schemas enable configuration validation and autocompletion in popular IDEs and CI/CD pipelines.

Introduction

A Spring Boot starter library uses Spring Context to process @ConfigurationProperties annotated classes and relevant properties from Spring Boot’s configuration metadata (spring-configuration-metadata.json) to generate JSON Schema. The generated schema can be used by compatible editors for configuration validation and assistance outside the Java project, as well as for configuration validation during CI/CD pipelines.

A good article on this subject: Spring Boot Config Documentation, Two Ways With IntelliJ IDEA

Features

Core Capabilities

  • Automatic JSON Schema generation from @ConfigurationProperties classes

  • Support for Jakarta Bean Validation (JSR-380) annotations

  • Full Spring Boot 3.x compatibility

  • Java 17+ runtime support

Integration Support

  • Built-in REST API endpoint for schema access

  • IDE integration (IntelliJ IDEA, VS Code)

  • Unit test helpers for schema generation

  • CI/CD pipeline validation

Schema Features

  • Nested property support

  • Complex type handling

  • Custom validation rules

  • Comprehensive property metadata

Prerequisites

  • Java 17 or higher

  • Spring Boot 3.x

  • Maven or Gradle build system

  • Configuration processor for property metadata generation:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

Usage

Maven (using in unit tests)

Add the following dependency to your pom.xml:

<dependency>
    <groupId>org.alexmond</groupId>
    <artifactId>spring-boot-config-json-schema-starter</artifactId>
    <version>1.0.3</version>
    <scope>test</scope>
</dependency>
SampleJsonSchemaGeneratorTests.java
@SpringBootTest
@Slf4j
class SampleJsonSchemaGeneratorTests {

    @Autowired
    private JsonSchemaService jsonSchemaService;

     @Test
    void generateJsonSchema() {

        var jsonConfigSchemaJson = jsonSchemaService.generateFullSchemaJson();
        var jsonConfigSchemaYaml = jsonSchemaService.generateFullSchemaYaml();
        log.info("Writing json schema");
        Files.writeString(Paths.get("config-schema.json"), jsonConfigSchemaJson, StandardCharsets.UTF_8);

        log.info("Writing yaml schema");
        Files.writeString(Paths.get("config-schema.yaml"), jsonConfigSchemaYaml, StandardCharsets.UTF_8);
    }
}

Using as REST API Endpoint

To expose the JSON schema via a REST endpoint (similar to Swagger API docs), first add the following dependency to your pom.xml:

<dependency>
    <groupId>org.alexmond</groupId>
    <artifactId>spring-boot-config-json-schema-starter</artifactId>
    <version>1.0.3</version>
</dependency>
GenerateJsonSchema.java
@RestController
@Slf4j
public class GenerateJsonSchema {

    @Autowired
    private JsonSchemaService jsonSchemaService;

    @GetMapping("/config-schema")
    public String getConfigSchema() {
        return jsonSchemaService.generateFullSchemaJson();
    }

    @GetMapping("/config-schema.yaml")
    public String getConfigSchemaYaml() throws Exception {
        return jsonSchemaService.generateFullSchemaYaml();
    }
}

Using as Actuator Endpoint

To expose the JSON schema via an Actuator endpoint, first add the following dependency to your pom.xml:

<dependency>
    <groupId>org.alexmond</groupId>
    <artifactId>spring-boot-config-json-schema-starter</artifactId>
    <version>1.0.3</version>
</dependency>

In JSON format

ConfigSchemaEndpoint.java
@Component
@Endpoint(id = "config-schema")
@RequiredArgsConstructor
public class ConfigSchemaEndpoint {

    private final JsonSchemaService jsonSchemaService;

    @ReadOperation
    public String schema() {
        return jsonSchemaService.generateFullSchemaJson();
    }
}

In YAML format

ConfigSchemaYamlEndpoint.java
@Component
@Endpoint(id = "config-schema.yaml")
@RequiredArgsConstructor
public class ConfigSchemaYamlEndpoint {

    private final JsonSchemaService jsonSchemaService;

    @ReadOperation
    public String schema() throws Exception {
        return jsonSchemaService.generateFullSchemaYaml();
    }
}

Using in editors

IDE Integration

IntelliJ IDEA and JetBrains IDEs

Add schema reference to the top of your YAML configuration

For testing purposes, you can find sample generic schema files here:

# Schema reference for JetBrains IDEs
$schema: "https://alexmond.github.io/spring-boot-config-json-schema-starter/current/_attachments/boot-generic-config.json"

# Application properties
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    username: sa
    password: password

Examples:

Intellij1
Intellij2

Usage in Visual Studio Code

Add schema reference using YAML language server directive (requires YAML Language Support by Red Hat extension):

# yaml-language-server: $schema=https://alexmond.github.io/spring-boot-config-json-schema-starter/current/_attachments/boot-generic-config.yaml

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    username: sa
    password: password

Examples:

vcs1
vcs2

Configuration Properties

Below you can find a list of configuration properties.

Configuration Properties

Description of all available configuration properties for JSON Schema generation.

Name Default Value Description

json-config-schema.additional-properties

logging

Additional property paths to include in the schema generation. Default includes 'logging' namespace.

json-config-schema.description

Auto-generated schema from configuration metadata

Description text for the generated schema document.

json-config-schema.missing-type-log

false

When true, logs any property types that couldn’t be resolved during schema generation.

json-config-schema.schema-id

your-schema-id

Unique identifier for the generated schema.

json-config-schema.schema-spec

https://json-schema.org/draft/2020-12/schema

JSON Schema specification URL to use. Defaults to 2020-12 draft.

json-config-schema.title

Spring Boot Configuration Properties

Title for the schema document.

json-config-schema.use-openapi

true

Enable/disable OpenAPI annotation processing for schema enhancement.

json-config-schema.use-validation

true

Enable/disable validation annotation processing for constraint inclusion.

json-config-schema.type-properties-map

{}

Map of property type overrides for schema generation. Allows customizing type mappings.