Porting guide for users coming from orjson #642

msgspec's performance is generally on par with that of orjson. For some schemas we're faster, for some orjson is faster. For common message schemas though things should be about the same.

There are some valid reasons a user might prefer to migrate from orjson to msgspec.json instead:

• msgspec also can handles schema validation using python type hints, similar to (but faster than) pydantic. Adding types also generally makes parsing faster, while providing stronger guarantees to the user.
• A wide set of supported builtin types.
• Possibly more reliable. Some recent orjson releases have led to segfaults for some users (see e.g. the saga of https://github.com/ijl/orjson/issues/452, https://github.com/ijl/orjson/pull/457, https://github.com/ijl/orjson/pull/459). While in rust, orjson is mostly a shim around the yyjson C library, and makes use of unsafe in several places, which can let memory safety issues sneak through. msgspec is all in C so we're not necessarily better 😬, but we do seem to have a lighter history of segfault bug reports.

For most users that aren't passing additional config options to orjson, porting should be as straightforward as swapping calls to orjson.loads to msgspec.json.decode and orjson.dumps to msgspec.json.encode. For other options we generally have a corollary, but the spelling is different. A short porting/comparison guide might be useful here.