Pydantic Schema Development (Research-Driven)

Constitution Alignment

This skill enforces project principles:

• •IV. Contract-Driven Integration: CompiledArtifacts is the SOLE contract between packages
• •Pydantic v2: ALL schemas use Pydantic with model_config = ConfigDict(frozen=True, extra="forbid")
• •JSON Schema Export: All contracts export JSON Schema for IDE autocomplete
• •Contract Versioning: MAJOR (breaking), MINOR (additive), PATCH (docs only)

Philosophy

This skill does NOT prescribe specific patterns. Instead, it guides you to:

1. •Research the current Pydantic version and capabilities
2. •Discover existing patterns in the codebase
3. •Validate your implementations against SDK documentation
4. •Verify backward compatibility and contract stability

Pre-Implementation Research Protocol

Step 1: Verify Runtime Environment

ALWAYS run this first:

python -c "import pydantic; print(f'Pydantic {pydantic.__version__}')"

Critical Questions to Answer:

• •What version is installed? (v1 or v2?)
• •Does it match the documented requirements?
• •Are there breaking changes from the docs?

Step 2: Research SDK State (if unfamiliar)

When to research: If you encounter unfamiliar Pydantic features or need to validate syntax

Research queries (use WebSearch):

• •"Pydantic v2 [feature] documentation 2025"
• •"Pydantic v2 breaking changes from v1"
• •"Pydantic v2 best practices [specific use case]"

SDK documentation: https://docs.pydantic.dev/latest/

Step 3: Discover Existing Patterns

BEFORE creating new schemas, search for existing implementations:

# Find existing Pydantic models
rg "class.*\(BaseModel\)" --type py

# Find field validators
rg "@field_validator|@model_validator" --type py

# Find ConfigDict usage
rg "model_config.*ConfigDict" --type py

Key questions:

• •What patterns are already in use?
• •Are they using v1 or v2 syntax?
• •What validation patterns exist?

Step 4: Validate Against Requirements

Check API-REFERENCE.md for known v2 patterns, then verify:

• •Are you using v2 syntax (@field_validator, NOT @validator)?
• •Are you using model_config = ConfigDict(...), NOT class Config:?
• •Are type hints present on ALL fields and methods?
• •Are secrets using SecretStr (not str)?

Implementation Guidance (Not Prescriptive)

Contract Design Principles

When designing contract schemas (like CompiledArtifacts):

• •Consider immutability: frozen=True prevents accidental mutations
• •Consider strict validation: extra="forbid" rejects unknown fields
• •Consider versioning: Use semantic versioning for contract changes
• •Consider backward compatibility: Only add optional fields in minor versions

Research questions:

• •What are the actual integration points? (Read architecture docs)
• •Who are the consumers of this contract?
• •What changes would break compatibility?

Security Considerations

When handling sensitive data:

• •Research: What fields contain secrets? (passwords, API keys, tokens)
• •Validate: Are you using SecretStr for sensitive fields?
• •Verify: Are secrets excluded from logs and error messages?

SDK feature to research: pydantic.SecretStr usage and .get_secret_value() pattern

Configuration Models

When building configuration from environment variables:

• •Research: pydantic-settings package (separate from core Pydantic)
• •Discover: What env var naming conventions exist in the codebase?
• •Validate: Are you using SettingsConfigDict with appropriate env_prefix?

SDK feature to research: pydantic_settings.BaseSettings and SettingsConfigDict

Validation Workflow

Before Implementation

1. •✅ Verified Pydantic version
2. •✅ Searched for existing patterns in codebase
3. •✅ Read architecture docs to understand requirements
4. •✅ Identified security requirements (secrets, PII)
5. •✅ Researched unfamiliar Pydantic features

During Implementation

1. •✅ Using from __future__ import annotations
2. •✅ Type hints on ALL fields and methods
3. •✅ Using v2 syntax (@field_validator, model_config)
4. •✅ Secrets using SecretStr (not str)
5. •✅ Contract models using frozen=True and extra="forbid"

After Implementation

1. •✅ Run type checker: mypy --strict [file]
2. •✅ Verify JSON schema export works: Model.model_json_schema()
3. •✅ Test validation with invalid data
4. •✅ Test serialization/deserialization
5. •✅ Check backward compatibility if modifying existing contracts

Context Injection (For Future Claude Instances)

When this skill is invoked, you should:

1. •

   Verify runtime state (don't assume):

   bash

   python -c "import pydantic; print(pydantic.__version__)"
   

2. •

   Discover existing patterns (don't invent):

   bash

   rg "class.*\(BaseModel\)" --type py
   

3. •

   Research when uncertain (don't guess):

   • •Use WebSearch for "Pydantic v2 [feature] documentation 2025"
   • •Check official docs: https://docs.pydantic.dev/latest/
4. •

   Validate against architecture (don't assume requirements):

   • •Read relevant architecture docs in /docs/
   • •Understand the actual contract requirements
   • •Check for existing schema definitions

Quick Reference: Common Research Queries

Use these WebSearch queries when encountering specific needs:

• •Field validation: "Pydantic v2 field_validator examples 2025"
• •Model validation: "Pydantic v2 model_validator cross-field validation"
• •Settings: "pydantic-settings BaseSettings environment variables 2025"
• •Secrets: "Pydantic v2 SecretStr SecretBytes best practices"
• •JSON Schema: "Pydantic v2 model_json_schema custom schema"
• •Performance: "Pydantic v2 performance optimization tips 2025"
• •Migration: "Pydantic v1 to v2 migration guide breaking changes"

References

• •API-REFERENCE.md: Curated v2 API changes and migration patterns
• •Pydantic Documentation: Official SDK documentation
• •pydantic-settings: Environment variable configuration

Remember: This skill provides research guidance, NOT prescriptive patterns. Always:

1. •Verify the runtime environment
2. •Discover existing codebase patterns
3. •Research SDK capabilities when needed
4. •Validate against actual requirements