Overview

This project contains Jackson extension component for reading and writing YAML encoded data. SnakeYAML library is used for low-level YAML parsing. 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.13.4</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();
JsonParser parser = factory.createParser(yamlString); // don't be fooled by method name...
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.

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