Micronaut TOML

Support for the TOML configuration format for the Micronaut framework

Version: 3.1.0

1 Introduction

TOML is a configuration format that easy to read, easy to write, and easy to parse.

Using this module, the Micronaut framework supports config files in the TOML format. This makes for configuration that is easier to read than Java Properties, but is also faster to parse than YAML (and does not rely on indentation).

2 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-toml/releases

3 Quick Start

To add support for TOML to an existing project, you should add the Micronaut TOML module to your build configuration. For example:

implementation("io.micronaut.toml:micronaut-toml")

<dependency>
    <groupId>io.micronaut.toml</groupId>
    <artifactId>micronaut-toml</artifactId>
</dependency>

You can then start using TOML for your application configuration:

Minimal application.toml

[micronaut.application]
name = "example"

3.1 TOML Serde

The toml-serde module integrates TOML with Micronaut Serialization. Use this module when you need to read or write TOML with ObjectMapper.

Add the following artifact to the dependencies block:

implementation("io.micronaut.toml:micronaut-toml-serde")

<dependency>
    <groupId>io.micronaut.toml</groupId>
    <artifactId>micronaut-toml-serde</artifactId>
</dependency>

The TOML module contributes a named mapper bean. Inject @Named(TomlObjectMapper.NAME) when an application has more than one ObjectMapper:

package example;

import io.micronaut.serde.ObjectMapper;
import io.micronaut.serde.toml.TomlObjectMapper;
import jakarta.inject.Named;
import jakarta.inject.Singleton;

@Singleton
final class TomlService {
    private final ObjectMapper tomlMapper;

    TomlService(@Named(TomlObjectMapper.NAME) ObjectMapper tomlMapper) {
        this.tomlMapper = tomlMapper;
    }

    ObjectMapper tomlMapper() {
        return tomlMapper;
    }
}

With the correct dependencies in place you can now define an object to be serialized:

package example;

import io.micronaut.serde.annotation.Serdeable;

@Serdeable
public class Book {
    private final String title;
    private final int pages;

    public Book(String title, int pages) {
        this.title = title;
        this.pages = pages;
    }

    public String getTitle() {
        return title;
    }

    public int getPages() {
        return pages;
    }
}

The type is annotated with @Serdeable to enable serialization and deserialization. The constructor is used to create the deserialized bean, and bean properties are written as TOML keys.

Once you have a type that can be serialized and deserialized you can use the TOML ObjectMapper bean to do so:

package example;

import io.micronaut.serde.ObjectMapper;
import io.micronaut.serde.toml.TomlObjectMapper;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Named;
import org.junit.jupiter.api.Test;

import java.io.IOException;

import static org.junit.jupiter.api.Assertions.assertEquals;

@MicronautTest
public class BookTest {

    @Test
    void testWriteReadBook(@Named(TomlObjectMapper.NAME) ObjectMapper tomlMapper) throws IOException {
        String result = tomlMapper.writeValueAsString(new Book("The Stand", 50));

        Book book = tomlMapper.readValue(result, Book.class);
        assertEquals("The Stand", book.getTitle());
        assertEquals(50, book.getPages());
    }
}

The mapper also supports the generic Argument<T> overloads when the target type has generic parameters.

TOML Mapper Configuration

TOML-specific mapper configuration is under micronaut.serde.toml. The available settings are:

micronaut.serde.toml.write-features.write-layout - controls serialized TOML output layout. Supported values are table and inline; the default is table.
micronaut.serde.toml.read-constraints.max-document-size - maximum TOML document size in bytes before parsing. The default is 1048576 bytes, and a non-positive value disables the limit.
micronaut.serde.toml.read-constraints.max-string-length - maximum string value length. The default has no TOML-specific limit.
micronaut.serde.toml.read-constraints.max-number-length - maximum number token length. The default uses the parser default.

micronaut.serde.toml.write-features.write-layout=table
micronaut.serde.toml.read-constraints.max-document-size=1048576
micronaut.serde.toml.read-constraints.max-string-length=65536
micronaut.serde.toml.read-constraints.max-number-length=1000

micronaut:
  serde:
    toml:
      write-features:
        write-layout: table
      read-constraints:
        max-document-size: 1048576
        max-string-length: 65536
        max-number-length: 1000

micronaut = {serde = {toml = {write-features = {write-layout = "table"}, read-constraints = {max-document-size = 1048576, max-string-length = 65536, max-number-length = 1000}}}}

micronaut {
  serde {
    toml {
      writeFeatures {
        writeLayout = "table"
      }
      readConstraints {
        maxDocumentSize = 1048576
        maxStringLength = 65536
        maxNumberLength = 1000
      }
    }
  }
}

{
  micronaut {
    serde {
      toml {
        write-features {
          write-layout = "table"
        }
        read-constraints {
          max-document-size = 1048576
          max-string-length = 65536
          max-number-length = 1000
        }
      }
    }
  }
}

{
  "micronaut": {
    "serde": {
      "toml": {
        "write-features": {
          "write-layout": "table"
        },
        "read-constraints": {
          "max-document-size": 1048576,
          "max-string-length": 65536,
          "max-number-length": 1000
        }
      }
    }
  }
}

The general Micronaut Serialization settings under micronaut.serde.* still apply to the TOML mapper where relevant. For example, serialization inclusion settings affect empty values, while TOML text still omits null properties because TOML has no null literal.

TOML Output Layout

The TOML mapper writes nested object graphs in table layout by default. For example, a bean with an author property is written with a TOML table header:

title = 'Micronaut in Action'
pages = 320

[author]
name = 'Ada'

Arrays of objects are written as arrays of tables:

[[products]]
name = 'Hammer'
sku = 738594937

[[products]]
name = 'Nail'
sku = 284758393

Configure the mapper to write nested objects with TOML inline tables instead:

micronaut.serde.toml.write-features.write-layout=inline

micronaut:
  serde:
    toml:
      write-features:
        write-layout: inline

micronaut = {serde = {toml = {write-features = {write-layout = "inline"}}}}

micronaut {
  serde {
    toml {
      writeFeatures {
        writeLayout = "inline"
      }
    }
  }
}

{
  micronaut {
    serde {
      toml {
        write-features {
          write-layout = "inline"
        }
      }
    }
  }
}

{
  "micronaut": {
    "serde": {
      "toml": {
        "write-features": {
          "write-layout": "inline"
        }
      }
    }
  }
}

With inline layout, the same nested values are written as inline table values:

title = 'Micronaut in Action'
pages = 320
author = {name = 'Ada'}

An array of objects is written as a single inline array value:

products = [{name = 'Hammer', sku = 738594937}, {name = 'Nail', sku = 284758393}]

Set micronaut.serde.toml.write-features.write-layout to table to select the default table output explicitly. The write layout only controls serialization output. The mapper can read valid TOML that uses standard table headers, arrays of tables, inline tables, or inline arrays.

TOML has no null literal. When writing TOML text, null object properties are omitted. The TOML mapper also expects the serialized root value to be an object, because a complete TOML document is a set of key/value pairs and tables.

4 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-toml

Table of Contents