spec-driven

Align OpenAPI/OpenRPC contracts with Pydantic models and services.

Updated Jan 28, 2026

Search Tags:#pydantic #openapi #models #contracts #api-design #openrpc #contracts-first

Ready to run

npx skills add https://github.com/mesca/claude-plugins --skill spec-driven-mesca

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: spec-driven
Source: https://github.com/mesca/claude-plugins/tree/main/plugins/wf/skills/spec-driven
Command: npx skills add https://github.com/mesca/claude-plugins --skill spec-driven-mesca

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

API projects often suffer from drift between contracts (OpenAPI/OpenRPC) and implementation, leading to broken integrations and flaky tests.

Core Features & Use Cases

Contracts-first guidance: define the authoritative API surface in contracts/ (OpenAPI/OpenRPC) and derive models and services from it.
Models-first development: align Pydantic models with contract schemas before coding, ensuring data consistency.
End-to-end discipline: maintain parity across contracts, models, tests, and implementation with versioned artifacts.

Quick Start

Define the OpenAPI/OpenRPC contracts in contracts/ and derive aligned models in models/ before implementing services.

Frequently Asked Questions about spec-driven

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I prevent drift between OpenAPI schemas and Pydantic models?▼

Contracts-first API design prevents drift by defining authoritative OpenAPI or OpenRPC schemas in contracts/ first. You then derive models in models/ from these schemas, ensuring strict synchronization and parity between contract definitions and implementation layers.

What's the best way to align JSON-RPC contracts with service implementation?▼

The best way to align JSON-RPC contracts with implementation is to define authoritative OpenRPC schemas in contracts/ first. You then generate models in models/ and enforce strict synchronization between schema definitions, tests, and service code to maintain versioned parity.

How do I start a contracts-first API workflow for REST and JSON-RPC projects?▼

Start a contracts-first API workflow by defining OpenAPI or OpenRPC schemas in a contracts/ directory. Once contracts are established, derive aligned Pydantic models in models/ before implementing services to ensure end-to-end data consistency.

Does contracts-first API design work with Pydantic models?▼

Yes, contracts-first API design works with Pydantic models by enforcing models-first development. You align Pydantic models with OpenAPI or OpenRPC contract schemas before coding, ensuring data consistency and strict parity across contracts, models, tests, and implementation.

Why does my API implementation keep breaking during integration?▼

API implementation breaks during integration due to drift between contracts and implementation. Without contracts-first API design enforcing strict synchronization between OpenAPI schemas and data models, schema definitions and services lose parity, resulting in broken integrations and flaky tests.