Why structtype?

If you’re writing a networked application, you’ll need some agreed upon protocol that your clients and servers can use to communicate. JSON is a decent choice here (though there are many other options). It’s ubiquitous, and Python has many libraries for parsing it into builtin types (json, ujson, orjson, …).

However, servers don’t just parse JSON, they also need to do something with it.

structtype goes above and beyond other Python JSON libraries to help with the following:

  • Validation

    If a field is missing from a request or has the wrong type, you probably want to raise a nice error message rather than just throwing a 500 error.

    structtype lets you describe your schema via type annotations, and will efficiently validate messages against this schema while decoding.

    It also integrates well with static analysis tools like mypy and pyright, helping you avoid whole classes of runtime errors.

  • Application Logic

    What your application actually does! While builtin types like dicts are fine for writing application logic, they aren’t as ergonomic as custom classes (no attribute access, poor type checking, …).

    structtype supports a wide variety of types, letting you decouple the objects your application logic uses from those that JSON natively supports.

  • Future Flexibility

    Application needs change; you’ll want to make sure your clients/servers won’t break if the JSON schema evolves over time.

    To handle this, structtype supports “schema evolution”. Messages can be sent between clients with different schemas without error, allowing systems to evolve over time.

While there are other tools in this space, structtype should be an order of magnitude faster than other options. We also hope that it’s quick to learn and friendly to use, letting you focus less on serialization and more on your application code.

Relationship to msgspec

structtype is a focused fork of the excellent msgspec library. The core C encoder/decoder code is from msgspec, with this project extracting and streamlining the Struct type and its minimal helpers. The goals of this fork are:

  • Provide only the Struct type with all serialization methods directly on the class (no separate Encoder/Decoder objects needed for common use).

  • Remove msgspec’s msgpack and YAML protocols, keeping only JSON.

  • Ship as a lightweight, zero-dependency library focused on schema validation and JSON serialization.