How JSON Resume Schema Validation Works in models.py: A Complete Guide to Pydantic Implementation

JSON Resume schema validation in the interviewstreet/hiring-agent repository uses Pydantic models in models.py to enforce type safety, validate nested structures, and constrain numeric ranges, automatically raising detailed ValidationError exceptions when resume data violates the specification.

The interviewstreet/hiring-agent repository implements robust resume processing through a comprehensive Pydantic-based schema validation system. In models.py, the entire JSON Resume specification is modeled as a hierarchy of Python classes inheriting from pydantic.BaseModel, providing automatic type checking, data normalization, and constraint enforcement when parsing candidate resumes throughout the application pipeline.

Pydantic Model Architecture

The validation system centers on models.py, where each class mirrors a specific section of the JSON Resume specification. Core models include Basics, Work, Education, and the top-level JSONResume container class.

All models inherit from pydantic.BaseModel, which provides the foundational validation infrastructure. When a dictionary representing a resume is passed to JSONResume(**data), Pydantic automatically parses the input against the defined schema, coercing types where possible and flagging violations immediately.

Four-Layer Validation Strategy

The schema implements a comprehensive validation approach covering type safety, optional fields, numeric constraints, and structural integrity.

Strict Type Enforcement

Every attribute in models.py declares explicit types using standard Python annotations such as str, Optional[str], List[Dict], and nested model references. If incoming data does not match the expected type—such as passing an integer where a string is required—Pydantic raises a ValidationError pinpointing the exact field and expected format.

Optional Field Flexibility

Fields declared as Optional[...] = None may be omitted without triggering validation errors, matching the flexible nature of the JSON Resume specification. This allows resumes to contain partial information while still conforming to the schema, accommodating varying levels of detail in candidate submissions.

Numeric Range Constraints

Specific fields enforce business logic through Pydantic's Field constraints. For example, CategoryScore.score uses ge=0 to ensure scores cannot be negative, while BonusPoints.total applies ge=0, le=20 to restrict values between 0 and 20. These constraints are defined directly in the model declarations:

from pydantic import BaseModel, Field

class CategoryScore(BaseModel):
    score: int = Field(ge=0)  # Must be >= 0

    max: int
    evidence: str

class BonusPoints(BaseModel):
    total: int = Field(ge=0, le=20)  # Must be between 0 and 20

Recursive Nested Validation

Nested structures are validated recursively. When a model contains references to other models—such as basics: Optional[Basics] or nested Location objects—Pydantic validates each child object against its own schema. This ensures that complex, multi-level resume structures maintain integrity throughout the entire object graph.

Integration Across the Codebase

The validation layer integrates at critical points in the resume processing pipeline, specifically within evaluator.py and transform.py.

Validating LLM Outputs in evaluator.py

The ResumeEvaluator class in evaluator.py utilizes the schema to validate responses from Large Language Models (LLMs). After receiving a JSON payload from an LLM call, the code constructs an EvaluationData object, triggering Pydantic validation. Additionally, EvaluationData.model_json_schema() generates a JSON Schema dictionary that serves as a format hint for LLM requests, ensuring the AI returns structured data that matches the expected validation rules.

Transforming Raw Data in transform.py

In transform.py, the transform_parsed_data function processes raw resume input and builds a dictionary that is later validated against the JSONResume model. At line 506, the code passes this parsed dictionary to JSONResume(**parsed), initiating the full validation cascade before further processing occurs.

Practical Validation Examples

The following examples demonstrate the validation system in action:

Creating a Valid Resume Object

from models import JSONResume, Basics, Location

resume = JSONResume(
    basics=Basics(
        name="Jane Doe",
        email="jane@example.com",
        location=Location(city="San Francisco", countryCode="US"),
        profiles=[{"network": "GitHub", "username": "janedoe", "url": "https://github.com/janedoe"}],
    ),
    work=[
        {
            "name": "Acme Corp",
            "position": "Software Engineer",
            "startDate": "Jan 2020",
            "endDate": "Present",
            "summary": "Worked on APIs",
        }
    ],
)
print(resume.json())

Triggering Validation Errors

from models import CategoryScore

try:
    # score must be >= 0; passing -5 raises ValidationError

    bad_score = CategoryScore(score=-5, max=10, evidence="Test")
except Exception as e:
    print(e)
    # Output: 1 validation error for CategoryScore

    # score

    #   ensure this value is greater than or equal to 0

Using Schema as LLM Format Hints

from models import EvaluationData

format_schema = EvaluationData.model_json_schema()

# Returns JSON schema describing expected LLM output structure

print(format_schema)

Summary

• Pydantic BaseModel inheritance in models.py provides the foundation for JSON Resume validation in the interviewstreet/hiring-agent repository.
• Four validation layers enforce type safety, optional field handling, numeric constraints (using Field(ge=0) and Field(ge=0, le=20)), and recursive nested structure validation.
• Integration points include evaluator.py for LLM response validation and transform.py (line 506) for incoming resume data processing.
• Automatic error reporting via Pydantic's ValidationError provides detailed field-level feedback when schema violations occur.

Frequently Asked Questions

What happens when JSON Resume validation fails?

Pydantic raises a detailed ValidationError that identifies the exact field causing the issue, the expected type or constraint, and the actual value received. This allows the application to catch malformed resumes in evaluator.py or transform.py and report specific errors to users or logging systems.

How does the schema handle optional resume sections?

Fields declared as Optional[Type] = None in models.py allow sections to be omitted without triggering validation errors. This design accommodates the flexible JSON Resume specification, where candidates may not provide complete information for every category like Education or Work history.

Can the Pydantic models be used as LLM format hints?

Yes, according to the implementation in evaluator.py, calling EvaluationData.model_json_schema() generates a JSON Schema representation of the model. This schema is passed to LLM requests as a format specification, guiding the AI to return structured data that will pass validation when instantiated as a Pydantic model.

Where does the actual JSON Resume validation occur in the pipeline?

Validation occurs at multiple checkpoints: primarily in transform.py at line 506 where JSONResume(**parsed) validates transformed raw data, and in evaluator.py where EvaluationData objects validate LLM responses. Any instantiation of these Pydantic models triggers the full validation cascade.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}