go-yaml

goccy/go-yaml is a from-scratch YAML library for Go designed to replace the aging go-yaml/yaml (gopkg.in/yaml). It ships with zero external dependencies, passes more of the official YAML Test Suite than gopkg.in/yaml.v3, and exposes public Tokenizer, Parser, and AST layers so tools can manipulate YAML documents directly instead of only working through struct tags.

Beyond basic Marshal/Unmarshal, it supports YAML Path queries for filtering and replacing content, anchor/alias resolution across files via ReferenceDirs, struct-tag-driven anchors and merge keys, JSON-tag compatibility, custom marshaler/unmarshaler hooks, and pretty-printed, optionally colorized parse errors that point at the offending source location.

What You Get

• Zero-dependency Encoder/Decoder with a gopkg.in/yaml.v2/v3-compatible Marshal/Unmarshal API
• Public lexer, parser, and AST packages for building custom YAML tooling
• YAML Path support for querying, filtering, and replacing values without hand-written traversal
• Anchor/alias handling, including cross-file references via ReferenceDirs and merge-key support on embedded structs
• Pretty-formatted, optionally colorized parse errors annotated with the source YAML

Common Use Cases

• Parsing and validating application or service configuration files with precise error locations
• Building CLIs or editors that need to programmatically rewrite YAML while preserving comments, anchors, and formatting
• Extracting values from large YAML documents with YAML Path instead of manual struct walking
• Replacing gopkg.in/yaml.v2 or v3 in existing codebases that need better spec coverage or clearer errors

Under The Hood

Architecture The library is structured as a classic compiler-style pipeline wrapped by a reflection-based binding layer: the token package defines lexical tokens, lexer (lexer.Tokenize) turns source text into a token stream, scanner does the character-level scanning underneath it, and parser (parser.Parse) consumes tokens to build a typed ast.File tree. The root yaml package layers Decoder/Encoder (in decode.go/encode.go) and reflection-based struct binding (struct.go) on top of that AST, while path.go implements the YAMLPath query engine by combining the parser with the printer package for source-annotated output. This separation means the reflection-based Marshal/Unmarshal API and direct AST manipulation are independent consumers of the same lexer/parser core, and the bundled cmd/ycat CLI sits entirely outside the core packages.

Tech Stack Built for Go 1.21+ with genuinely zero third-party runtime dependencies (go.sum is empty) — a deliberate contrast to libraries that wrap C-derived libyaml bindings. The optional go-playground/validator integration is kept out of the top-level go.mod and scoped to the testdata directory to avoid pulling test-only dependencies into consumers. Tooling is standard Go: a Makefile driving golangci-lint (errcheck, govet, ineffassign, misspell, perfsprint, staticcheck, unused) and a GitHub Actions matrix testing ubuntu/macOS/Windows across four Go versions, plus dedicated i386 and -race jobs.

Code Quality Test coverage is extensive: dedicated _test.go files sit alongside every package (decode, encode, path, ast, parser, lexer, token, printer), plus a suite that runs the official external YAML Test Suite and a native Go fuzz test. Errors are explicit and typed rather than stringly-typed or swallowed — a shared Error interface (GetToken, GetMessage, FormatError) is implemented by distinct SyntaxError, TypeError, OverflowError, DuplicateKeyError, UnknownFieldError, and UnexpectedNodeTypeError types, alongside sentinel errors checked via errors.Is/errors.As. CI enforces linting and race-tested builds across multiple OSes and Go versions before merge.

API Design The public API deliberately mirrors gopkg.in/yaml.v2’s Marshal/Unmarshal signatures and accepts both yaml and json struct tags, so migrating from the incumbent library is close to a drop-in swap, while layering on ergonomics the older library lacks: exported Tokenizer/Parser/AST packages for YAML-aware tooling, a query-string YAMLPath language (yaml.PathString("$.store.book[*].author")) for extracting or replacing nested values without traversal code, struct-tag-driven anchor/alias declarations (yaml:"c,anchor=x") that let idiomatic Go control YAML’s non-scalar features, and FormatError/AnnotateSource helpers that render parse failures against the original source text with optional coloring.