Pydantic Validation for ML Endpoints

1. The First Line of Defense: Field Constraints

Pydantic's most straightforward validation method beyond simple type hints is using the Field function. It allows you to add constraints directly to your model's attributes. For our Iris dataset, a fundamental rule is that all measurements must be positive.

Let's modify your IrisFeatures schema to enforce this. You'll import Field from Pydantic and use it to declare that each feature must be greater than zero (gt=0).

Update your Pydantic model (likely in schemas.py or main.py) to look like this:

from pydantic import BaseModel, Field




# In previous lessons, this might have been named IrisFeatures
class PredictionInput(BaseModel):
    sepal_length: float = Field(..., gt=0, description="Sepal length in cm")
    sepal_width: float = Field(..., gt=0, description="Sepal width in cm")
    petal_length: float = Field(..., gt=0, description="Petal length in cm")
    petal_width: float = Field(..., gt=0, description="Petal width in cm")

A quick note on the syntax:

• Field(...): The ellipsis (...) indicates that this field is required.
• gt=0: This is the constraint, meaning "greater than 0". Other options include lt (less than), ge (greater than or equal to), and le (less than or equal to).

After updating your code, restart your Uvicorn server. Go to the Swagger UI at http://127.0.0.1:8000/docs, try to execute a prediction with a negative value for any feature, and observe the response. FastAPI will automatically catch the validation error from Pydantic and return a 422 Unprocessable Entity error with a descriptive message.

The video below demonstrates how these automatic validation errors appear in FastAPI.

2. Advanced Logic with Custom Validators

Field constraints are great for simple rules, but what about more complex, domain-specific logic? For example, in most iris species, the petal is shorter than the sepal. An input where petal_length > sepal_length might be a sign of a measurement error.

Pydantic's validators, implemented as methods with decorators, are the perfect tool for this. Since you are proficient with Python decorators, this pattern should feel familiar.

There are two main types of validators:

• @field_validator: Operates on a single field's data.
• @model_validator: Operates on the entire model's data, allowing for cross-field validation.

For our use case—comparing petal_length and sepal_length—we need @model_validator.

Let's start by looking at a concise article that uses @field_validator. While its example validates the length of a list, the structure and principle are identical.

Now, let's apply this concept to our IrisFeatures schema using @model_validator to enforce our cross-field rule.

Update your PredictionInput model again with the following code.

from pydantic import BaseModel, Field, model_validator
from typing import Self # Import Self for type hinting

class PredictionInput(BaseModel):
    sepal_length: float = Field(..., gt=0, description="Sepal length in cm")
    sepal_width: float = Field(..., gt=0, description="Sepal width in cm")
    petal_length: float = Field(..., gt=0, description="Petal length in cm")
    petal_width: float = Field(..., gt=0, description="Petal width in cm")

    @model_validator(mode='after')
    def check_petal_sepal_lengths(self) -> Self:
        """
        Check that petal length is not greater than sepal length.
        """
        if self.petal_length >= self.sepal_length:
            raise ValueError("Domain error: petal length cannot be greater than or equal to sepal length.")
        return self

Key points about this code:

• @model_validator(mode='after'): This decorator registers the method as a validator. mode='after' means it runs after Pydantic has validated and populated the individual fields. This ensures self.petal_length and self.sepal_length are already validated float values when we access them.
• check_petal_sepal_lengths(self) -> Self: The method receives self, which is an instance of the model. This gives you access to all its fields.
• raise ValueError(...): If your custom rule is violated, you raise a ValueError. FastAPI will intercept this and, just as before, return a 422 error with your custom message.
• return self: If validation passes, you must return the model instance.

To dive deeper into the mechanics of custom validators, the following video offers a comprehensive explanation.

3. Testing Your Robust API

With your new validator in place, it's time to test it.

1. Restart your Uvicorn server to load the updated code.
2. Open your browser to the Swagger UI at http://127.0.0.1:8000/docs.
3. Navigate to your POST /predict endpoint and click "Try it out".
4. Test the validation logic by providing an input that should fail, for example:

   {
     "sepal_length": 5.0,
     "sepal_width": 3.0,
     "petal_length": 6.0,
     "petal_width": 2.0
   }
   

5. Execute the request.

You should receive a 422 Unprocessable Entity response. In the response body, you will see your custom error message: "Domain error: petal length cannot be greater than or equal to sepal length."

You have successfully hardened your API against invalid domain-specific inputs!

Conclusion

In this lesson, you've significantly improved the reliability of your machine learning API. By adding custom validation, you ensure that only clean, sensible data reaches your model, preventing unexpected errors and improving the quality of your predictions.

Key Takeaways:

• Default type validation is often insufficient for ML models; domain-specific validation is crucial.
• Pydantic's Field function is a simple way to add constraints like value ranges (gt, lt, etc.) to single fields.
• The @field_validator decorator allows for custom validation logic on individual fields.
• The @model_validator decorator is used for complex rules that require checking multiple fields at once.
• Raising a ValueError within a validator signals a failure, which FastAPI automatically translates into a user-friendly 422 error response.

In our next lesson, we will continue to build a more resilient API. We'll ask the question: what happens if the input data passes all our validation checks, but the model.predict() call itself fails for some reason? We will learn to implement specific error handling for exceptions that may occur during model inference.