API Conventions: Booleans are disallowed in OpenShift APIs
@@ -406,6 +406,39 @@ may be accustomed to from upstream APIs, but it has the advantage that it avoids
ambiguity and the need for API consumers to resolve an API version and kind to
the resource group and name that identify the resource.
+### Do not use Boolean fields
+
+While the upstream Kubernetes conventions recommend thinking twice about using Booleans, they are explicitly forbidden
+within OpenShift APIs.
+
+Many ideas start as a boolean value, eg `FooEnabled: true|false`, but often evolve into needing 3, 4 or even more states
+at some point during the APIs lifetime.
+As a Boolean value can only ever have 3 values (`true`, `false`, `omitted` when a pointer), we have seen examples in
+where API authors have later added additional fields, paired with the Boolean field that are only meaningful when the
+original field has a certain state. This makes it confusing for an end user as they have to be aware that the field
+they are trying to use, only has an effect in certain circumstances.
+
+Rather than creating a boolean field:
+```go
+// authenticationEnabled determines whether authentication should be enabled or disabled.
+// When omitted, this means the platform can choose a reasonable default.
+// +optional
+AuthenticationEnabled *bool `json:"authenticationEnabled,omitempty"`
+```
+
+Use an enumeration of values that describe the action instead:
+```go
+// authentication determines the requirements for authentication within the cluster.
+// When omitted, the authentication will be Optional.
+// +kubebuilder:validation:Enum:=Optional;Required;Disabled;""
+// +optional
+Authentication AuthenticationPolicy `json:authentication,omitempty`
+```
+
+With this example, we have described through the enumerated values the action that the API will have.
+Should the API need to evolve in the future, for example to add a particular method of Authentication that should be
+used, we can do so by adding a new value (eg. `PublicKey`) to the enumeration and avoid adding a new field to the API.
+
## FAQs
### My proposed design looks like an existing API we have, why am I being told that it must be changed?
