orjson Python
Treat JSON as a wire/storage contract. Decide the accepted Python domain, JSON
shape, text/bytes boundary, datetime and integer policy, key ordering, and error
behavior before selecting options.
Boundary
Use this skill when the project imports orjson or explicitly requests it. Do
not introduce orjson solely from a vague performance claim; benchmark the real
payload and preserve the surrounding interface. orjson encodes/decodes values;
it does not own file I/O, JSON Lines framing, schema validation, HTTP content
types, or format/comment preservation.
Know the values
| Object |
Contract |
orjson.dumps(value, ...) |
Returns UTF-8 JSON as bytes, never str. |
orjson.loads(data) |
Accepts UTF-8 bytes, bytearray, memoryview, or str; returns ordinary Python JSON values. |
default(obj) |
Converts one unsupported object to a supported value or raises TypeError. |
option bitmask |
Explicitly changes encoding semantics; combine flags with ` |
JSONEncodeError |
Serialization contract failure; a TypeError subclass. |
JSONDecodeError |
Invalid input/type/depth failure; compatible with json.JSONDecodeError/ValueError. |
Fragment |
Injects already-serialized JSON without validation/escaping; a trust boundary. |
Read serialization contracts before replacing
stdlib json, encoding temporal values, or accepting arbitrary keys.
Ordered workflow
- Recover the external contract: JSON shape, field names, accepted input
types, byte/text owner, newline/framing, datetime/timezone form, number
limits, ordering, and error mapping.
- Inspect the installed orjson version and the existing adapter. Preserve a
public
str return only by decoding once at that boundary; preserve bytes
for binary HTTP/file/socket APIs.
- Start with no options. Add one option only for a named contract requirement,
not because an example includes it.
- Use native supported types where their semantics match. Add a narrow
default dispatcher for project-owned unsupported types; never return an
unsupported object or stringify every unknown value.
- Keep I/O/framing outside
dumps and loads. Add exactly one newline per
JSON-lines record; do not parse an entire JSONL file as one JSON value.
- Map encode/decode errors at the application boundary without swallowing the
input location/cause or leaking payloads.
- Test exact decoded structure plus byte-level requirements such as newline,
key order, timezone spelling, or rejection behavior.
Decision table
| Requirement |
Action |
| Binary response/body/file API |
Pass dumps bytes directly. |
Text API explicitly requires str |
Decode UTF-8 once at the outer boundary. |
| Input already bytes-like |
Pass it to loads; do not decode first. |
| Pretty human file |
Use indentation only if whitespace is contractual; append newline deliberately. |
| JSON Lines |
Encode each record separately and delimit records; do not wrap in an array. |
Datetime contract requires UTC Z |
Normalize awareness/policy, then use the verified UTC option or explicit adapter. |
| Naive datetime has no declared timezone |
Reject or normalize before encoding; do not silently invent local/UTC meaning. |
| Non-string dict keys are part of the schema |
Confirm supported key domains and collision risks before the non-string-key option. |
| JavaScript-safe integer range is required |
Enable strict integer behavior or validate at the domain boundary. |
| Deterministic lexical key order is required |
Use sorted keys and test bytes; do not call it canonical JSON without a full canonicalization spec. |
| Unknown object |
Serialize through a type-specific default; otherwise raise. |
Canonical boundary
from decimal import Decimal
from pathlib import Path
from typing import Any
import orjson
def default(value: Any) -> Any:
if isinstance(value, Decimal):
return format(value, "f") # schema declares a decimal string
if isinstance(value, Path):
return value.as_posix() # schema declares a POSIX path string
raise TypeError(f"unsupported type: {type(value).__name__}")
def encode_event(event: object) -> bytes:
return orjson.dumps(event, default=default)
def decode_event(payload: bytes | bytearray | memoryview | str) -> dict[str, Any]:
value = orjson.loads(payload)
if not isinstance(value, dict):
raise ValueError("event JSON must be an object")
return value
loads validates JSON syntax, not the application shape. Validate the returned
object separately. default normally sees only types orjson does not already
serialize natively; dataclasses and datetimes need passthrough options before a
custom handler can override their native representation. A default function
must raise TypeError for unsupported values so contract errors remain visible.
High-risk options and integration
- Option flags are not general best practices. Each changes observable output
or accepted types and needs a protecting test.
- Native datetime serialization does not decide the business meaning of naive
values. Establish timezone policy before encoding.
- Non-string keys can serialize different Python keys to the same JSON member
name; reject ambiguity when round-tripping or signatures matter.
- Pretty printing, key sorting, and newline flags add work. Use them for a
contract, not a generic speed path.
Fragment trusts its bytes as JSON and skips validation/escaping. Accept it
only from a controlled serialized source, never raw user text.
- In web frameworks, adapt to their response class/renderer contract. Avoid a
second
json.dumps around orjson bytes and set the JSON media type.
Read options and integration for these
branches.
Error and verification contract
Invalid input, unsupported objects, non-finite values, excessive depth, integer
limits, and invalid UTF-8 need explicit behavior. Do not return {}/None on a
decode failure unless that fallback is a documented domain rule. Test malformed
JSON and unsupported types, not only round trips; a lossy encoder can round-trip
its own mistake.
Read testing JSON behavior. This foundry did not have
orjson installed during authoring, so its cases use static/source evidence and
must not be described as local runtime validation. Completion requires exact
outer type (bytes or str), declared temporal/number/key semantics, narrow
custom encoding, correct framing, explicit shape validation, and negative tests
for malformed and unsupported input.
References
- Serialization contracts
- Options and integration
- Testing JSON behavior
1---2name: orjson-python3description: Use for writing, reviewing, debugging, or testing Python JSON serialization and deserialization with orjson, including bytes/text boundaries, datetimes, dataclasses, NumPy, custom default handlers, option flags, strictness, and web/file integration. Do not use for JSON Schema validation, format-preserving JSON edits, streaming I/O frameworks, or choosing a JSON library when orjson is not requested or present.4argument-hint: "[orjson serialization task, contract, code, or failure]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/orjson-python7---89# orjson Python1011Treat JSON as a wire/storage contract. Decide the accepted Python domain, JSON12shape, text/bytes boundary, datetime and integer policy, key ordering, and error13behavior before selecting options.1415## Boundary1617Use this skill when the project imports orjson or explicitly requests it. Do18not introduce orjson solely from a vague performance claim; benchmark the real19payload and preserve the surrounding interface. orjson encodes/decodes values;20it does not own file I/O, JSON Lines framing, schema validation, HTTP content21types, or format/comment preservation.2223## Know the values2425| Object | Contract |26|---|---|27| `orjson.dumps(value, ...)` | Returns UTF-8 JSON as `bytes`, never `str`. |28| `orjson.loads(data)` | Accepts UTF-8 `bytes`, `bytearray`, `memoryview`, or `str`; returns ordinary Python JSON values. |29| `default(obj)` | Converts one unsupported object to a supported value or raises `TypeError`. |30| `option` bitmask | Explicitly changes encoding semantics; combine flags with `|`. |31| `JSONEncodeError` | Serialization contract failure; a `TypeError` subclass. |32| `JSONDecodeError` | Invalid input/type/depth failure; compatible with `json.JSONDecodeError`/`ValueError`. |33| `Fragment` | Injects already-serialized JSON without validation/escaping; a trust boundary. |3435Read [serialization contracts](references/data-contracts.md) before replacing36stdlib `json`, encoding temporal values, or accepting arbitrary keys.3738## Ordered workflow39401. Recover the external contract: JSON shape, field names, accepted input41 types, byte/text owner, newline/framing, datetime/timezone form, number42 limits, ordering, and error mapping.432. Inspect the installed orjson version and the existing adapter. Preserve a44 public `str` return only by decoding once at that boundary; preserve bytes45 for binary HTTP/file/socket APIs.463. Start with no options. Add one option only for a named contract requirement,47 not because an example includes it.484. Use native supported types where their semantics match. Add a narrow49 `default` dispatcher for project-owned unsupported types; never return an50 unsupported object or stringify every unknown value.515. Keep I/O/framing outside `dumps` and `loads`. Add exactly one newline per52 JSON-lines record; do not parse an entire JSONL file as one JSON value.536. Map encode/decode errors at the application boundary without swallowing the54 input location/cause or leaking payloads.557. Test exact decoded structure plus byte-level requirements such as newline,56 key order, timezone spelling, or rejection behavior.5758## Decision table5960| Requirement | Action |61|---|---|62| Binary response/body/file API | Pass `dumps` bytes directly. |63| Text API explicitly requires `str` | Decode UTF-8 once at the outer boundary. |64| Input already bytes-like | Pass it to `loads`; do not decode first. |65| Pretty human file | Use indentation only if whitespace is contractual; append newline deliberately. |66| JSON Lines | Encode each record separately and delimit records; do not wrap in an array. |67| Datetime contract requires UTC `Z` | Normalize awareness/policy, then use the verified UTC option or explicit adapter. |68| Naive datetime has no declared timezone | Reject or normalize before encoding; do not silently invent local/UTC meaning. |69| Non-string dict keys are part of the schema | Confirm supported key domains and collision risks before the non-string-key option. |70| JavaScript-safe integer range is required | Enable strict integer behavior or validate at the domain boundary. |71| Deterministic lexical key order is required | Use sorted keys and test bytes; do not call it canonical JSON without a full canonicalization spec. |72| Unknown object | Serialize through a type-specific `default`; otherwise raise. |7374## Canonical boundary7576```python77from decimal import Decimal78from pathlib import Path79from typing import Any8081import orjson828384def default(value: Any) -> Any:85 if isinstance(value, Decimal):86 return format(value, "f") # schema declares a decimal string87 if isinstance(value, Path):88 return value.as_posix() # schema declares a POSIX path string89 raise TypeError(f"unsupported type: {type(value).__name__}")909192def encode_event(event: object) -> bytes:93 return orjson.dumps(event, default=default)949596def decode_event(payload: bytes | bytearray | memoryview | str) -> dict[str, Any]:97 value = orjson.loads(payload)98 if not isinstance(value, dict):99 raise ValueError("event JSON must be an object")100 return value101```102103`loads` validates JSON syntax, not the application shape. Validate the returned104object separately. `default` normally sees only types orjson does not already105serialize natively; dataclasses and datetimes need passthrough options before a106custom handler can override their native representation. A `default` function107must raise `TypeError` for unsupported values so contract errors remain visible.108109## High-risk options and integration110111- Option flags are not general best practices. Each changes observable output112 or accepted types and needs a protecting test.113- Native datetime serialization does not decide the business meaning of naive114 values. Establish timezone policy before encoding.115- Non-string keys can serialize different Python keys to the same JSON member116 name; reject ambiguity when round-tripping or signatures matter.117- Pretty printing, key sorting, and newline flags add work. Use them for a118 contract, not a generic speed path.119- `Fragment` trusts its bytes as JSON and skips validation/escaping. Accept it120 only from a controlled serialized source, never raw user text.121- In web frameworks, adapt to their response class/renderer contract. Avoid a122 second `json.dumps` around orjson bytes and set the JSON media type.123124Read [options and integration](references/options-integration.md) for these125branches.126127## Error and verification contract128129Invalid input, unsupported objects, non-finite values, excessive depth, integer130limits, and invalid UTF-8 need explicit behavior. Do not return `{}`/`None` on a131decode failure unless that fallback is a documented domain rule. Test malformed132JSON and unsupported types, not only round trips; a lossy encoder can round-trip133its own mistake.134135Read [testing JSON behavior](references/testing.md). This foundry did not have136orjson installed during authoring, so its cases use static/source evidence and137must not be described as local runtime validation. Completion requires exact138outer type (`bytes` or `str`), declared temporal/number/key semantics, narrow139custom encoding, correct framing, explicit shape validation, and negative tests140for malformed and unsupported input.141142## References143144- [Serialization contracts](references/data-contracts.md)145- [Options and integration](references/options-integration.md)146- [Testing JSON behavior](references/testing.md)