yaml

Overview

This project contains Jackson extension component for reading and writing YAML encoded data. Since version 3.0, which is being developed in this branch, SnakeYAML Engine library will be used for low-level YAML parsing. In current released versions 2.* SnakeYAML library is used. See separate branches 2.9 and 2.10 for sources. This project adds necessary abstractions on top to make things work with other Jackson functionality.

Project is licensed under Apache License 2.0.

Status

Module has been production ready since version 2.5.

Maven dependency

To use this extension on Maven-based projects, use following dependency:

<dependency>
  <groupId>com.fasterxml.jackson.dataformat</groupId>
  <artifactId>jackson-dataformat-yaml</artifactId>
  <version>2.14.2</version>
</dependency>

Usage

Simple usage

Usage is through basic JsonFactory and/or ObjectMapper API but you will construct instances differently:

// Mapper with default configuration
ObjectMapper mapper = new YAMLMapper();
User user = mapper.readValue(yamlSource, User.class);

// Or using builder
ObjectMapper mapper = YAMLMapper.builder()
   .disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER)
   .build();
Json

but you can also just use underlying YAMLFactory and parser it produces, for event-based processing:

YAMLFactory factory = new YAMLFactory();
YAMLParser parser = factory.createParser(yamlString);
while (parser.nextToken() != null) {
  // do something!
}

Configuration

Most configuration is applied during mapper instance configuration, through YAMLMapper.Builder, similar to how JSON-based plain ObjectMapper is configured.

SnakeYAML Configuration

Since jackson-dataformat-yaml 2.14, it is possible to configure the underlying SnakeYAML behavior.

If you are parsing YAML, you might consider configuring the LoaderOptions. See the related 'Known Problems' section below to see an example of how to do this. As well as configuring the 'codePointLimit', you might also want to configure the 'nestingDepthLimit'.

If you are generating YAML, you can also control the underlying SnakeYAML behavior by setting the DumperOptions on the YAMLFactory.builder().

Known Problems

Maximum input YAML document size (3 MB)

SnakeYAML implementation (that Jackson uses for low-level encoding and decoding) starts imposing the default limit of 3 megabyte document size as of version 1.32, used by Jackson 2.14 (and later). If you hit this limitation, you need to explicitly increase the limit by configuring YAMLFactory and constructing YAMLMapper with that:

LoaderOptions loaderOptions = new LoaderOptions();
loaderOptions.setCodePointLimit(10 * 1024 * 1024); // 10 MB
YAMLFactory yamlFactory = YAMLFactory.builder()
    .loaderOptions(loaderOptions)
    .build();
YAMLMapper mapper = new YAMLMapper(yamlFactory);

Documentation

• Wiki contains links to Javadocs, external documentation