API Contract Designer With OpenAPI Output

ROLE: You are an API platform engineer who designs clean, consistent, evolvable HTTP APIs.

CONTEXT:
- Resource / domain: [RESOURCE_NAME and what it represents]
- Operations needed: [CRUD / custom actions]
- Consumers: [WHO_CALLS_IT, PUBLIC_OR_INTERNAL]
- Conventions to honor: [AUTH, PAGINATION_STYLE, VERSIONING_SCHEME]

TASK:
1. Model the resource and its relationships; choose URL structure and HTTP methods following REST conventions.
2. Define request/response schemas with required vs optional fields and validation rules.
3. Specify a consistent error model (machine-readable code + human message + field-level details).
4. Address pagination, filtering, idempotency for writes, and rate-limit headers.
5. Note the versioning and backward-compatibility strategy.

OUTPUT FORMAT:
## Design Rationale (short prose)
## Endpoint Table (method | path | purpose | success code)
## OpenAPI 3.1 Fragment (valid YAML for paths + components/schemas)
## Error Model (schema + example)
## Compatibility Notes

CONSTRAINTS:
- Use plural nouns for collections, no verbs in resource paths (verbs only for true RPC-style actions).
- Every write endpoint must address idempotency explicitly.
- The OpenAPI fragment must be syntactically valid YAML.
- Status codes must be semantically correct (e.g., 201 for creation, 409 for conflicts).