Custom Media Types
Register media type strategies to make Schemathesis send valid payloads for media types it cannot generate, such as PDFs, images or archives.
Prerequisites
- Schemathesis installed or available via
uvx - An operation whose
requestBody.content(or a multipart field'sencoding) declares the media type
Quick Start: PDF File Upload
Your API accepts PDF uploads, but without a registered strategy Schemathesis sends arbitrary bytes that the API rejects before reaching its PDF handling. Register a strategy that produces PDF documents:
# pdf_strategy.py
from hypothesis import strategies as st
import schemathesis
pdf_strategy = st.sampled_from(
[
b"%PDF-1.4\n1 0 obj\n<<\n/Type /Catalog\n/Pages 2 0 R\n>>\nendobj\nxref\n0 3\n0000000000 65535 f \ntrailer\n<<\n/Size 3\n/Root 1 0 R\n>>\nstartxref\n9\n%%EOF",
b"%PDF-1.5\n%\xe2\xe3\xcf\xd3\n1 0 obj\n<<\n/Type /Catalog\n/Pages 2 0 R\n>>\nendobj\nxref\n0 3\n0000000000 65535 f \ntrailer\n<<\n/Size 3\n/Root 1 0 R\n>>\nstartxref\n9\n%%EOF",
]
)
# Register the strategy for PDF media type
schemathesis.openapi.media_type("application/pdf", pdf_strategy)
export SCHEMATHESIS_HOOKS=pdf_strategy
uvx schemathesis run http://localhost:8000/openapi.json
Operations that accept application/pdf receive one of these documents as the request body.
Media Type Matching
A registered strategy is used when the media type in your schema matches it exactly (application/pdf), through a wildcard (image/*), or through one of its aliases. application/x-pdf in the schema does not match application/pdf unless you register it as an alias. Check your schema's requestBody.content section for the media type strings it uses.
Common Media Type Patterns
Use these imports in the snippets below:
from hypothesis import strategies as st
import schemathesis
Image files
# Minimal PNG
PNG = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\tpHYs\x00\x00\x0b\x13\x00\x00\x0b\x13\x01\x00\x9a\x9c\x18\x00\x00\x00\nIDAT\x08\x1dc\xf8\x00\x00\x00\x01\x00\x01\x00\x00\x00\x00IEND\xaeB`\x82"
# Minimal JPEG
JPEG = b"\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01\x01\x00H\x00H\x00\x00\xff\xdb\x00C\x00\x08\x06\x06\x07\x06\x05\x08\x07\x07\x07\t\t\x08\n\x0c\x14\r\x0c\x0b\x0b\x0c\x19\x12\x13\x0f\x14\x1d\x1a\x1f\x1e\x1d\x1a\x1c\x1c $.' \",#\x1c\x1c(7),01444\x1f'9=82<.342\xff\xc0\x00\x11\x08\x00\x01\x00\x01\x01\x01\x11\x00\x02\x11\x01\x03\x11\x01\xff\xc4\x00\x14\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\xff\xc4\x00\x14\x10\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xda\x00\x08\x01\x01\x00\x00?\x00\xff\xd9"
image_strategy = st.sampled_from([PNG, JPEG])
schemathesis.openapi.media_type("image/*", image_strategy)
Archives
import io
import zipfile
def create_test_zip():
"""Create a minimal valid ZIP file"""
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w") as zf:
zf.writestr("test.txt", "test content")
return buffer.getvalue()
zip_strategy = st.just(create_test_zip())
schemathesis.openapi.media_type("application/zip", zip_strategy)
Wildcard Patterns
The image/* registration from Image files covers every image type in your schema:
# Regular requestBody
requestBody:
content:
image/png: # Matches registered image/*
schema:
type: string
format: binary
# Multipart encoding
requestBody:
content:
multipart/form-data:
schema:
properties:
avatar:
type: string
format: binary
encoding:
avatar:
contentType: image/jpeg # Matches registered image/*
Wildcards work bidirectionally - you can register image/* and use image/png in your schema, or register image/png and use image/* in your schema.
Media Type Aliases
schemathesis.openapi.media_type(
"application/pdf",
pdf_strategy,
aliases=["application/x-pdf", "application/acrobat"],
)
pdf_strategy is then used for application/pdf, application/x-pdf and application/acrobat.
Dynamic Content Generation
A strategy can build each payload from generated parts:
@st.composite
def dynamic_xml(draw):
tag_name = draw(st.text(alphabet=st.characters(categories=["L"]), min_size=3, max_size=10))
content = draw(st.text(min_size=1, max_size=50))
return f"<?xml version='1.0'?><{tag_name}>{content}</{tag_name}>".encode()
schemathesis.openapi.media_type("application/xml", dynamic_xml())
Multipart Form Fields
When using multipart/form-data, you can specify custom content types for individual form fields using the encoding property. Schemathesis will automatically use your registered strategies for those fields:
# `pdf_strategy` is defined in the Quick Start
xml_strategy = st.just(b"<?xml version='1.0'?><root/>")
schemathesis.openapi.media_type("application/pdf", pdf_strategy)
schemathesis.openapi.media_type("text/xml", xml_strategy)
# Your OpenAPI schema
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
document:
type: string
format: binary
metadata:
type: string
format: binary
encoding:
document:
contentType: application/pdf # Uses PDF strategy
metadata:
contentType: text/xml # Uses XML strategy
The encoding.{field}.contentType tells Schemathesis which registered strategy to use for each form field. Fields without custom encoding use default generation.
Multiple Content Types
You can specify multiple acceptable content types for a field. Schemathesis will randomly choose between registered strategies:
# PNG and JPEG are defined in "Image files" above
schemathesis.openapi.media_type("image/png", st.just(PNG))
schemathesis.openapi.media_type("image/jpeg", st.just(JPEG))
encoding:
avatar:
contentType: "image/png, image/jpeg" # Randomly uses PNG or JPEG
Troubleshooting
The API still receives random bytes. Check that SCHEMATHESIS_HOOKS names the module that registers the strategy and that the media type in the schema matches the registration exactly, through a wildcard, or through an alias.
A strategy seems to be ignored for one of several registrations. With overlapping registrations, such as image/* and image/png, an exact match wins over a wildcard. Register the specific type if it needs different payloads.