RFC: Extract optional serialization formats from Gin core into gin-contrib

[thinkerou]

Move optional serialization formats to gin-contrib (Gin v2 proposal)

Category: Ideas
Labels (optional): proposal, v2, dependencies, breaking-change

---

TL;DR

I'm proposing we slim down Gin core by moving optional serialization formats into gin-contrib modules:

• Move out: YAML, TOML, BSON, Protobuf, MsgPack, alternative JSON backends (sonic, jsoniter, go-json)
• Keep in core: stdlib JSON (with a path to encoding/json/v2), XML, form/query/URI binding, HTML render
• Ship via: Gin v2 + a registration model (blank import to opt in)
• Migrate safely: Phase 1 build tags on v1 → v2 breaking change → v1 LTS period

---

Background

Importing github.com/gin-gonic/gin today pulls in many third-party serialization libraries, even if a project only uses JSON:

Dependency	Purpose
goccy/go-yaml	YAML
pelletier/go-toml/v2	TOML
google.golang.org/protobuf	Protobuf
go.mongodb.org/mongo-driver/v2	BSON
ugorji/go/codec	MsgPack
sonic / json-iterator / goccy/go-json	Alternative JSON backends

This affects us in two ways:

1. Module graph — all of the above show up as transitive deps in every consumer's go.mod / SBOM, whether or not they're used.
2. Binary size — binding and render are always linked from context.go, so YAML/TOML/BSON/Protobuf/MsgPack get compiled in even for JSON-only apps.

Gin already has patterns that point in this direction:

• gin-contrib for optional middleware (cors, sessions, zap, …)
• nomsgpack build tag to drop MsgPack at compile time
• JSON build tags (sonic, go_json, jsoniter) — only one backend is linked, but all remain in go.mod

With encoding/json/v2 on the horizon (golang/go#71497), this feels like a good time to simplify JSON in core and treat everything else as opt-in.

---

Proposal

Gin v2 core stays lean

In core	Why
JSON (stdlib → json/v2)	Default format
XML	stdlib
Form, Query, URI, Header, Plain, Multipart	No third-party deps
HTML render	stdlib

Optional formats move to gin-contrib

Suggested modules (names TBD):

Module	Registers
gin-contrib/format-yaml	YAML bind + render
gin-contrib/format-toml	TOML bind + render
gin-contrib/format-bson	BSON bind + render
gin-contrib/format-protobuf	Protobuf bind + render
gin-contrib/format-msgpack	MsgPack bind + render
gin-contrib/codec-sonic	Sonic JSON backend
gin-contrib/codec-gojson	go-json backend
gin-contrib/codec-jsoniter	json-iterator backend

Registration model (sketch)

Instead of hard-coded package vars in binding/binding.go, v2 would use something like:

// gin/v2 core
binding.Register("yaml", []string{"application/yaml", "application/x-yaml"}, yamlBinding{})

// consumer
import (
    "github.com/gin-gonic/gin/v2"
    _ "github.com/gin-contrib/format-yaml"
)

Contrib modules register both binding and render in init(), similar to database/sql drivers.

---

Migration plan (avoid a Python 2/3 situation)

Phase	What	Breaking?
1 — v1.x	Add build tags: noyaml, notoml, nobson, … (like nomsgpack)	No
2 — v2.0	New import path github.com/gin-gonic/gin/v2, registry API, formats in contrib	Yes (opt-in)
3 — v1 LTS	Security fixes on v1 for a defined period (suggest ≥ 12 months)	No
4 — Tooling	Migration guide, examples, optional codemod	—

v1 and v2 would coexist under different import paths — not a forced ecosystem split.

---

What would break in v2

• Package-level vars: binding.YAML, binding.TOML, binding.BSON, …
• Context helpers: BindYAML, c.YAML(), c.TOML(), c.BSON(), MsgPack render, etc.
• Negotiate() branches for formats not in core

Contrib modules could provide thin wrappers to preserve ergonomics:

yamlgin.Bind(c, obj)
yamlgin.Render(c, 200, obj)

---

Expected benefits

• Smaller default go.mod / SBOM surface for JSON-only projects
• Smaller default binary (format code no longer always linked)
• Consistent with gin-contrib philosophy
• Room to adopt encoding/json/v2 in core without carrying legacy JSON backends

---

Alternatives

Option	Trade-off
Build tags only	Helps binary size, not module graph; awkward DX. Good as Phase 1.
Keep everything in core	Status quo — deps keep growing.
Split packages inside main repo	Still one go get — doesn't fix transitive deps.

---

Questions for the community

I'd love maintainer and user feedback on these:

1. Is this direction worth pursuing for Gin v2, or are build tags on v1 enough?
2. Naming: one module per format (format-yaml) vs split binding/render modules?
3. Negotiate(): skip unregistered formats silently, or return a clear error?
4. JSON v2: should v2 block on encoding/json/v2 GA, or ship with stdlib v1 JSON first?
5. HTTP/3 (quic-go): separate RFC, or include in the same slimming effort?
6. v1 LTS: how long should v1 get security patches after v2 ships?
7. Ergonomics: should contrib modules re-export today's API (c.BindYAML, etc.), or is explicit registration enough?

---

References

• gin-contrib
• encoding/json/v2 — golang/go#71497
• Existing nomsgpack build tag (see README)

---

If there's interest, I can follow up with a more detailed technical design (registry interfaces, Negotiate behavior, and a before/after dependency diff).

What's your take?