Installation

pip install valbridge-pydantic pydantic
# or
uv add valbridge-pydantic pydantic

Verified against pydantic 2.12.5.

Usage

This adapter is invoked by the valbridge CLI. It is typically used when converting from Zod or other valbridge-supported schema sources into Pydantic models:

// user.valbridge.jsonc
{
  "$schema": "https://github.com/vectorfy-co/valbridge/schemas/python.jsonc",
  "schemas": [
    {
      "id": "User",
      "adapter": "vectorfyco/valbridge-pydantic",
      "sourceType": "file",
      "source": "./schemas/user.json"
    }
  ]
}

Then generate:

valbridge generate

Use the generated models with the valbridge runtime client.

Verification

Run from the adapter directory (python/packages/adapters/pydantic/):

# JSON Schema Test Suite compliance (requires Go CLI)
cd ../../cli && go build -o valbridge . && \
  ./valbridge compliance --lang python --adapter-path ../python/packages/adapters/pydantic

# Unit tests
uv run pytest

# Type checking
uv run pyright src/

Fallback typing guardrails

The adapter uses Annotated[Any, BeforeValidator(...)] only for constructs where the validated domain is unbounded. Every other construct must produce a narrower type.

Allowed Any fallbacks

Constructs that must NOT use Any

• oneOf -- must produce T1 | T2 | ...
• conditional (if/then/else) -- must produce ThenType | ElseType
• Closed tuples -- must produce tuple[T1, T2, ...]
• const / enum -- must produce the narrowest applicable type
• allOf (object merges) -- must produce a BaseModel subclass

Disallowed patterns

• Unknown IR node kind -- must raise ConversionError
• Unresolved external refs -- must raise ConversionError
• New renderer branches must not silently return Any without documented justification

Troubleshooting

• pyright errors -- adapter source must pass uv run pyright src/ with zero errors
• Compliance failures -- run full compliance and compare against baseline; check that validator lambdas are functionally identical

Related packages

Learn more

• GitHub repository
• Full documentation