cbor

fxamacker/cbor is a full RFC 8949 conformant CBOR (Concise Binary Object Representation) codec for Go that also supports CBOR Sequences (RFC 8742). It mirrors the encoding/json API surface — Marshal, Unmarshal, NewEncoder, NewDecoder — so teams already comfortable with Go’s standard JSON package can adopt CBOR with minimal retooling, while adding CBOR-specific capabilities such as tag support, Core Deterministic Encoding, and canonical CTAP2 encoding.

The library is used in production by projects tied to organizations including Kubernetes, IBM, Microsoft, Tailscale, Red Hat, and the Linux Foundation, and has undergone multiple confidential security assessments plus continuous fuzzing. Struct tag options (toarray, keyasint, omitempty, omitzero) shrink encoded payload size and reduce boilerplate, while configurable decoding limits defend against malicious or malformed input without sacrificing speed.

What You Get

• Marshal/Unmarshal functions with the same signatures as encoding/json for near drop-in adoption
• Reusable, concurrency-safe EncMode/DecMode objects built from immutable EncOptions/DecOptions
• Struct tag options (toarray, keyasint, omitempty, omitzero) that shrink encoded size and cut boilerplate
• Configurable decoder limits (max nesting, map/array size, duplicate map key detection) that reject malformed or adversarial CBOR quickly
• CBOR Sequences support via UnmarshalFirst/DiagnoseFirst for streaming multiple data items from one buffer
• Extended Diagnostic Notation output (Diagnose/DiagnoseFirst) for human-readable inspection of CBOR bytes

Common Use Cases

• Encoding COSE (CBOR Object Signing and Encryption) and CWT (CBOR Web Token) payloads with keyasint/toarray struct tags
• Replacing JSON in bandwidth- or CPU-constrained services (IoT, embedded, TinyGo targets) that still want a typed, self-describing format
• Implementing CTAP2/FIDO2 authenticator or relying-party code that must produce canonical CBOR
• Decoding untrusted CBOR input in security-sensitive services where malformed-data rejection speed matters
• Interoperating with non-Go CBOR implementations that expect Core Deterministic or Preferred Serialization encoding

Under The Hood

Architecture fxamacker/cbor is organized as a single well-factored Go package with clear internal separation of concerns: common.go defines the CBOR wire-format constants (major types, additional-information bytes, built-in tag numbers) shared by every other file; encode.go and decode.go implement the actual Marshal/Unmarshal machinery and are the largest files in the codebase; cache.go maintains a set of sync.Map-backed caches (decodingStructTypeCache, encodingStructTypeCache, encodeFuncCache, typeInfoCache) that memoize reflect-based type introspection so repeated encode/decode of the same Go type avoids re-deriving struct-tag layout on every call, which is central to both the library’s speed and its concurrency-safety story; stream.go layers CBOR Sequences (RFC 8742) support on top of the core codec; tag.go, simplevalue.go, and bytestring.go implement CBOR-specific data types as thin wrappers with their own Marshal/Unmarshal hooks; and diagnose.go implements Extended Diagnostic Notation independently of the binary codec path. The EncMode/DecMode pattern builds immutable, concurrency-safe encoder/decoder instances from EncOptions/DecOptions structs at startup, so runtime behavior can’t drift after modes are created.

Tech Stack The module (github.com/fxamacker/cbor/v2, go.mod requires go 1.24) has a single external dependency, github.com/x448/float16, for IEEE 754 half-precision float support — everything else is Go standard library (reflect, encoding, sync, cmp, slices, strconv). It leans on comparatively recent stdlib packages (cmp, slices), indicating the codebase tracks current Go releases rather than targeting older toolchains. CI runs the full matrix of race-detector tests, coverage-percentage gating, golangci-lint, CodeQL static analysis, and Go’s official vulnerability scanner on every change.

Code Quality Testing is extensive and enforced: hundreds of Test/Example function definitions across dedicated _test.go files (decode_test.go alone contains close to 200), a CI job that fails the build if statement coverage drops below a configured high threshold, and a separate race-detector test run. The lint configuration enables an unusually strict linter set for a Go project — security, cyclomatic-complexity, error-check, ineffectual-assignment, ASCII/bidi-character, and misspelling checks among others — with zero tolerance for reported issues. Error handling is idiomatic Go with typed, descriptive errors rather than panics for malformed input, and the project maintains a private continuous fuzzer plus CodeQL and vulnerability scanning.

API Design The public API deliberately mirrors encoding/json — Marshal, Unmarshal, NewEncoder, NewDecoder, and the Encoder/Decoder Encode/Decode methods share identical signatures with their stdlib counterparts, and the package documentation explicitly calls this out as the onboarding path for Go developers already familiar with JSON. Beyond that baseline, the API layers in CBOR-specific ergonomics through struct tags that require no additional code, immutable EncMode/DecMode objects created once (or from presets like CanonicalEncOptions/CTAP2EncOptions) and safely reused across goroutines, and dedicated sequence/diagnostic helpers for less common use cases. Getting started requires no configuration, while advanced encoding policy is opt-in and centralized in one options struct rather than scattered across function arguments.