Install & Compatibility
Where this runs
tested against v1.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.044s · 22MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.039s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
input_schema
✓ from inference_schema.schema_decorators import input_schema
output_schema
✓ from inference_schema.schema_decorators import output_schema
PandasParameterType
✓ from inference_schema.parameter_types import PandasParameterType
NumpyParameterType
✓ from inference_schema.parameter_types import NumpyParameterType
This quickstart demonstrates how to define input and output schemas for a Python function using `inference-schema` decorators. It uses `PandasParameterType` for structured DataFrame input and a simple dictionary for output. The decorators validate the incoming `input_data` against `sample_input_df` and ensure the function's return value conforms to `sample_output_dict`'s structure.
from inference_schema.schema_decorators import input_schema, output_schema
from inference_schema.parameter_types import PandasParameterType
import pandas as pd
import json
# Define sample input and output data structures
# These samples are used to infer the schema for validation and serialization
sample_input_df = pd.DataFrame({'feature1': [10.0, 20.0], 'feature2': [30.0, 40.0]})
sample_output_dict = {'prediction': [40.0, 60.0]}
@input_schema(PandasParameterType(sample_input_df))
@output_schema(sample_output_dict)
def predict(input_data: pd.DataFrame) -> dict:
"""
A dummy prediction function that takes a DataFrame and returns a dictionary.
The decorators handle validation of `input_data` and serialization of the return value.
"""
# Example prediction logic: sum of features
predictions = (input_data['feature1'] + input_data['feature2']).tolist()
return {'prediction': predictions}
# --- Example Usage ---
# This is how you'd typically call it, with input that matches the schema
input_for_prediction = pd.DataFrame({'feature1': [5.0, 15.0], 'feature2': [25.0, 35.0]})
result = predict(input_for_prediction)
print(f"Predicted result: {result}")
# If used in a web service, the input might come as JSON and be deserialized
# and validated into a DataFrame before reaching `predict` function.
# Example: raw_json_input = '{"feature1": [5.0, 15.0], "feature2": [25.0, 35.0]}'
# (framework would parse, inference-schema would validate/convert)
Debug
Known issues
gotchaThe `sample_input` and `sample_output` provided to the decorators are critical. They define the *structure and data types* of the expected input and output, not just placeholder values. Mismatches between the actual data at runtime and these samples will cause schema validation errors.fixAlways ensure your `sample_input` and `sample_output` accurately reflect the exact column names, keys, and data types (e.g., float, int, string) that your function expects and returns.
affects: All versions
breakingInference-schema pins its core dependency, `marshmallow`, to specific version ranges (e.g., `<3.18.0` for v1.8). If your project uses a different `marshmallow` version, it can lead to dependency conflicts or unexpected validation behavior.fixAlign your project's `marshmallow` version with the range specified by `inference-schema`, or consider using a dedicated virtual environment to isolate dependencies.
affects: All versions
gotchaWhen using `PandasParameterType`, the decorated function is expected to receive a `pandas.DataFrame` object. If you directly call the function with a different type (e.g., a dictionary or list) without it being processed by the schema, it will likely fail.fixEnsure that the input to the decorated function is a `pandas.DataFrame` or that the web framework integration correctly deserializes the raw request body into a DataFrame before passing it to your function.
affects: All versions using `PandasParameterType`
Errors
Common errors & fixes
marshmallow.exceptions.ValidationError: {'field_name': ['Invalid type.']}
The input data type for a specific field did not match the type inferred from the `sample_input` schema.
fixVerify that the data types in your actual input data (e.g., float vs. int, string vs. number) precisely match the types present in your `sample_input` DataFrame/dictionary.
AttributeError: 'dict' object has no attribute 'tolist'
The decorated function returned a dictionary, but the `output_schema` implied that a Pandas DataFrame was expected, or vice-versa, leading to an incompatible method call during serialization.
fixEnsure the function's return value strictly conforms to the structure implied by the `sample_output` provided to `@output_schema`. If `output_schema` expects a list of numbers, convert your DataFrame column to a list using `.tolist()`.
TypeError: Object of type 'DataFrame' is not JSON serializable
This error typically occurs when a web framework tries to serialize the output of your decorated function (which might be a `pandas.DataFrame`) directly to JSON, but the `output_schema` hasn't fully transformed it into a JSON-compatible type.
fixEnsure your `output_schema` (the `sample_output` dictionary/list) defines a structure that is inherently JSON-serializable (e.g., nested dictionaries and lists of primitive types). If your function returns a `DataFrame`, make sure the output schema forces its conversion to a list of dicts or similar.
Upgrade
Version history
1.8latest on PyPI · released May 17, 2024
Audit
Dependencies
marshmallowrequiredCore library for schema definition and validation.
numpyrequiredRequired for `NumpyParameterType` and often for internal data handling.
pandasrequiredRequired for `PandasParameterType` and commonly used for structured data input/output.