yaml-flock
A Jackson extension that lets a single YAML document mix flow and block style, chosen property by property, by annotating the model rather than configuring the writer.
Why
YAML earns its place for files that live in source control. It dispenses with the furniture that makes JSON too verbose to review — braces, brackets, quotes on every key, commas that a diff flags on the line above the one that changed.
Block style still costs something, though. One property per line is exactly right for a Spring
application.yml, where each line is a single variable. But as soon as the data has real
structure, that rule turns a screenful of file into mostly blank space. Flow style alone is not the answer
either: collapse everything and you get long lines that a diff reports as one wholesale change, which is the
property that made JSON unpleasant in the first place.
Choosing per property gives a middle ground. Values that belong together on one line go on one line; structure that deserves a line per entry keeps it. The same book, twenty lines in plain block style, is seven here — and it still diffs cleanly, because a changed page count is a changed word on one line.
details: {isbn: "0306406152", title: "Godel Escher Bach", year: 1979}
genres: [PHILOSOPHY, MATHEMATICS]
authors:
- {name: Douglas Hofstadter, sortKey: '0001', born: 1945}
editions:
first: {format: HARDBACK, pages: 777, published: 1979}
anniversary: {format: PAPERBACK, pages: 824, published: 1999}
Have a look
The specification
Fifteen scenarios, grouped by what they describe: flow style, block style, collections, forced quoting, and nesting. Each one asserts a complete document, so you can see the YAML each annotation produces rather than read a description of it.
Read the scenarios →A full example
A hundred-book catalogue, 771 lines, carrying every style at once — and the awkward cases on purpose: titles with colons, apostrophes and non-Latin scripts, and ISBNs where quoting turns on a check digit. Read back byte for byte on every build.
Explore catalog.yml →Using it
<dependency>
<groupId>io.github.ctgnz</groupId>
<artifactId>yaml-flock</artifactId>
<version>1.0.0</version>
</dependency>
Then one line, because the builder already carries the settings the library needs:
ObjectMapper mapper = new ObjectMapper(FlockYamlFactory.builder().build());
Three annotations do the work. @YamlFlowStyle writes a value inline, on a type or on a single
property — the latter being the only way to inline a collection, since there is no type to annotate on a
List<Genre>. @YamlBlockStyle is the override, one entry per line.
@YamlForceQuote always quotes a property, so a column reads the same way on every occurrence
rather than depending on each value.
Reading needs none of it. YAML style is a presentation choice, so a plain YAMLFactory parses
anything this writes — which the round-trip test checks rather than asserts.