Styxis
Company
Knowledge

Pydantic bytes schemas: separating input decoding from output serialization

Separate input and output directions in the API documentation so client and server do not expect different byte representations.

Pydantic bytes schemas: separating input decoding from output serialization

Decoding a byte field's input and serializing its output are contracts in different directions. A server may read input correctly while its validation schema describes an output format, leading clients to construct incompatible requests. Use the same input fixture to connect documentation with actual decoding behavior. [1, 2, 3]

What the primary source establishes

A report describes bytes JSON Schema using ser_json_bytes even in validation mode, while actual input decoding follows val_json_bytes. Its example describes a base64-decoding input field with a binary format in the generated schema. [1]

The handover decision

Documentation and server owners should use the same fixture to record input text, decoded bytes, and output text. Align the validation schema with the actual input policy. Keep schema_mode, declared_format, configured_input_format, and decoded_hex so a correct output setting cannot mask an incorrect input description. [1, 3]

A reference defined before the output

The illustrative input contract uses base64url. The validation schema should therefore declare base64url; declaring binary is the counterexample. Correct serialization settings on the output side do not resolve that input-direction discrepancy. [1, 3]

The scoped Truthound check

Truthound Core 3.3.2 can compare declared_format and configured_input_format prepared for validation mode with ColumnPairValidator. Run byte-decoding tests separately and retain decoded_hex. Matching format names does not authorize the contents of an arbitrary binary file. [1, 2, 3]

Limits and alternative choices

Comparing format names does not guarantee decoder security or arbitrary binary-file safety. Keep input and output schemas separate and add actual byte round-trip tests. When both directions use the same format, this fixture may not expose the directional confusion. [1, 3]

Application conditions

Prepare mode-specific schema and runtime-format records, retaining the decoded-byte reference for the same fixture.

Alternatives

Keep input and output schemas separate and add actual byte round-trip tests.

Limitations

  • Comparing format names does not guarantee decoder security or arbitrary binary-file safety.

Evidence

Event checked
Subject checked
Modified