A advanced Go library to work with YAML documents.
This is a hard fork of
goccy/go-yaml.
Early days. API remains subject to changes.
Warning
This library is still in its early days: a lot of work has been issued on top of our fork point
(edee2f91616c6d73112a13e7c0dbde72ce938877), and the exported API is still in flux.
The posture we have adopted for various so-YAML puzzles may also be debatable and might need to be revisited.
If you want a stable version of this library today, use upstream: github.com/goccy/go-yaml.
If you only need to hydrate Go values from YAML, use go.yaml.in/yaml/v3: it's stable, it's maintained, it works.
- At
go-openapiwe consume and produce a lot of YAML. A typical API spec can be a fairly large document, so we need an efficient parser for those, both in CPU cycles and memory. - We also face a lot of challenges dealing with YAML that your typical go program won't care about, like keeping the orde of keys, or the comments in a document.
What we need is:
- a relatively fast, memory-efficient YAML parser, written in pure go
- a low-level API to parse, transform and render YAML streams
- ways to process YAML without the need for an intermediate go value representation
In addition, we want this lib to bring tools for advanced work with YAML documents:
- a strict YAML 1.2 parser, with optional support for YAML 1.1
- full support of YAML constructs, including comments, aliases, tags, custom tags, non-scalar keys, directives etc
- verbatim rendering of a parsed document, without loss (e.g. comments, layout style, indentation, ordering)
- full YAML 1.2 support, strict by default, with optionally relaxed constraints
- codec for go:
Unmarshal,Marshal,Decoder,Encoder- also provides: fast, lossless
ToJSON(from YAML),FromJSON(to YAML) transforms and a JSON tokenizer
- also provides: fast, lossless
- low-level API: parser, renderer able to render a document verbatim, extract comments, etc
- document transforms (examples: colorizer, custom tag parser)
- YAML path expressions
- programmatic document API via
astrepresentation of a YAML document
See also our documentation for a detailed presentation of these features, and the differences with other libraries etc.
See the runnable examples in our go doc as well as the commented examples in thee documentation.
Our main design goal for this lib was to reduce peak memory usage as much as we could.
| - | go-openapi/go-yaml | yaml/go-yaml/v3 | goccy/go-yaml | | Timings | ||| | # Allocations | ||| | Peak memory | |||
By design limitations - they'll stay here:
- only support UTF-8 encoding
no UTF-16 support is offered: you need to encode any UTF-16 input prior to parsing.
Transitory limitations - we are currently working on those.
- no streaming support: can't parse from an
io.Readeryet - document size is currently limited to 2 GB
This library was forked from the work started by Masaaki Goshima (@goccy), which is maintained upstream at github.com/goccy/go-yaml.
We are grateful to Masaaki for this great piece of work. This fork tries to remain faithful to its spirit: an independent YAML 1.2 library that brings to go developers advanced insight into YAML subtleties.
Our work was also inspired by some of the ideas and designs proposed by:
- the YAML Test Suite, by
@ingydotnet. This inspired us a companion project to generate Conformance Test Suites, for YAML and JSON. - libfyaml(https://github.com/pantoniou/libfyaml), by
@pantoniou. Arguably one of the best YAML library out there (C). We've used it a lot as a yardstick to compare against. - the Perl reference parser, by
@ingydotnet. go.yaml.in/yaml/v3, by the go-yaml contributors (originally [@niemeyer][niemeyer], with ported seminal work fromKiril Simonov)- PyYAML for YAML 1.1 compatibility checks
- YAML 1.2 spec (2021)
- YAML 1.2 grammar
- YAML types (2005-)
Apache-2.0 — see LICENSE.
This is a hard fork of goccy/go-yaml, whose MIT licence permits it. That licence, and the terms of
every other component this library is built on, are recorded in the NOTICE.