ADR-027: JSON schemas published to GitHub Pages

Category: development Provenance: human

Decision

Publish CRD JSON schemas to GitHub Pages for IDE validation and auto-completion. Schemas are available at https://vriesdemichael.github.io/keycloak-operator/schemas/

Rationale

JSON schemas enable IDE validation and auto-completion for CRD YAML files. Developers get immediate feedback on invalid configurations before applying to cluster. Schemas are versioned alongside releases, allowing users to validate against specific operator versions. Publishing to GitHub Pages makes schemas publicly accessible without authentication. Integration with IDEs (VSCode, IntelliJ) improves developer experience.

Agent Instructions

Generate schemas with scripts/generate-crd-schemas.py when CRDs change. Publish to GitHub Pages at https://vriesdemichael.github.io/keycloak-operator/schemas/. Regenerate before releasing new operator versions to keep schemas in sync with CRD changes.

Rejected Alternatives

Don't publish schemas - rely on kubectl validation only

kubectl validation happens too late (at apply time). IDE validation catches errors during editing.

Bundle schemas in operator image

Not accessible to users writing CRDs. Can't use for IDE validation.