ADR-013: Pydantic models for Keycloak API

Category: architecture Provenance: guided-ai

Decision

Use auto-generated Pydantic models from Keycloak OpenAPI spec for all Keycloak Admin API interactions. All requests and responses are validated against these models.

Rationale

Data validation: Pydantic validates all request/response data against Keycloak API schema, catching errors before sending invalid data. This prevents runtime failures from schema mismatches, missing required fields, or incorrect data types. Automatic schema updates: Regenerate models when Keycloak API changes to stay in sync. IDE support: Auto-complete and type hints for all Keycloak API fields improve developer productivity. Self-documenting: Models document the exact structure expected by Keycloak Admin API.

Agent Instructions

Import models from keycloak_operator.models.keycloak_api (e.g., RealmRepresentation, ClientRepresentation). Use these models for all Keycloak API interactions, never construct dicts manually. Use _make_validated_request() in KeycloakAdminClient for automatic validation. Never edit src/keycloak_operator/models/keycloak_api.py manually - regenerate with scripts/generate-keycloak-models.sh when OpenAPI spec updates.

Rejected Alternatives

Manually construct request dictionaries

Error-prone, no validation, easy to miss required fields or use wrong types. Changes in Keycloak API would silently break requests.

Use generic API client without validation

Would catch errors only at runtime when Keycloak rejects invalid requests, making debugging harder and potentially causing reconciliation failures.