msgspec

msgspec is a high-performance Python library for encoding and decoding JSON, MessagePack, YAML, and TOML, built around a fast Struct type and zero-cost schema validation using standard type annotations. Rather than treating serialization and validation as separate concerns, msgspec is designed so decoding a message and validating it against a schema happen in a single pass, with benchmarks showing it can decode and validate JSON faster than orjson can decode alone.

At its core is msgspec.Struct, a compact, C-implemented alternative to dataclasses and attrs classes that is 5-60x faster for common operations while remaining lightweight, with no required dependencies. The library exposes format-specific encode/decode functions for each supported protocol, a JSON Schema generator, struct/dataclass-to-dict conversion helpers, and a runtime type-introspection module, making it suitable both as a standalone drop-in JSON/MessagePack encoder and as the full validation layer for APIs and message-passing systems.

What You Get

• Format-specific encode/decode APIs for JSON, MessagePack, YAML, and TOML behind a consistent interface
• A C-implemented Struct type that serializes 5-60x faster than dataclasses or attrs
• Zero-cost schema validation performed during decoding, with typed ValidationError messages that include the failing path
• A JSON Schema generator (msgspec.json.schema) for producing schemas directly from Struct/dataclass/TypedDict definitions
• A runtime type-introspection module (msgspec.inspect) for programmatically walking type schemas
• Struct-to-dict/dict-to-struct conversion helpers (msgspec.convert, msgspec.to_builtins) for interop with plain Python data

Common Use Cases

• Validating and parsing incoming JSON payloads in web APIs and RPC services without a separate validation library
• Replacing dataclasses/attrs/pydantic models with Structs for hot paths where allocation and (de)serialization speed matter
• Producing JSON Schema documents for OpenAPI specs directly from existing Python type definitions
• Encoding/decoding MessagePack for compact binary message passing between services or into caches
• Reading and writing TOML/YAML configuration files against a typed schema

Under The Hood

Architecture msgspec is layered around a single CPython C extension (src/msgspec/_core.c, ~23k lines) that implements the Struct type and every format’s low-level encoder/decoder; thin Python wrapper modules (json.py, msgpack.py) simply re-export the C-level encode/decode functions, while toml.py and yaml.py wrap the C core’s to_builtins/convert primitives with the optional tomli/pyyaml dependencies for the two formats without native codecs. Pure-Python modules layered on top of that core — inspect.py for schema introspection, structs.py for struct metadata/field access, _json_schema.py for JSON Schema generation — all consume the same small set of C-level primitives (Factory, StructMeta, to_builtins), giving a clean split between the performance-critical codec/validation engine and the ergonomic, swappable Python-level tooling built on it.

Tech Stack The project targets Python 3.10+ and is built as a CPython C extension via setuptools + setuptools-scm (configured entirely in pyproject.toml, no setup.cfg), with optional extras (tomli/tomli_w for TOML on Python <3.11, pyyaml for YAML) kept out of the required dependency set so the core library stays dependency-free. Documentation is built with Sphinx and the furo theme; linting runs through ruff and codespell; type-checking runs three separate checkers (mypy, pyright, pyrefly) in strict mode against a dedicated typing-test suite, and performance regressions are tracked via pytest-codspeed against benchmarks comparing against orjson, pydantic, cattrs, mashumaro, and ujson.

Code Quality The test suite spans per-format unit tests (test_json.py, test_msgpack.py, test_toml.py, test_yaml.py), a dedicated JSON conformance suite (test_JSONTestSuite.py), constraint and conversion tests, struct-metaclass tests, and a custom C-lint test (test_cpylint.py) that checks the extension source itself. A separate tests/typing/basic_typing_examples.py file is checked against all three configured type checkers in CI, and the package ships py.typed plus hand-written .pyi stubs alongside the C extension. CI runs across multiple dedicated workflows for wheel builds, docs, and performance profiling, in addition to the main test matrix.

API Design The public API deliberately mirrors dataclasses and attrs — a Struct is defined the same way a dataclass is, so migrating existing models costs little more than a subclass change — while every supported wire format exposes the identical encode/decode function pair under its own submodule (msgspec.json, msgspec.msgpack, msgspec.toml, msgspec.yaml), so switching formats is a one-line import change. Validation piggybacks on the same type annotations used to define the schema rather than requiring a parallel schema language, and the JSON Schema generator, converter, and introspection module all consume that same annotation model, keeping validation, schema export, and plain-dict interop as one consistent surface instead of three separate APIs to learn.