Document how "schemaless" interacts with CEL rules

pkg/apis/postgres-operator.crunchydata.com/v1beta1/shared_types.go

@@ -81,7 +81,7 @@ func NewDuration(s string) (*Duration, error) {
 	return &Duration{metav1.Duration(umd), s}, err
 }
 
-// AsDuration returns d as a [metav1.Duration].
+// AsDuration returns a copy of d as a [metav1.Duration].
 func (d *Duration) AsDuration() metav1.Duration {
 	return d.parsed
 }
@@ -139,12 +139,18 @@ func (spec *VolumeClaimSpec) AsPersistentVolumeClaimSpec() corev1.PersistentVolu
 	return out
 }
 
+// ---
 // SchemalessObject is a map compatible with JSON object.
 //
 // Use with the following markers:
-// - kubebuilder:pruning:PreserveUnknownFields
-// - kubebuilder:validation:Schemaless
-// - kubebuilder:validation:Type=object
+//   - kubebuilder:pruning:PreserveUnknownFields
+//   - kubebuilder:validation:Schemaless
+//   - kubebuilder:validation:Type=object
+//
+// NOTE: PreserveUnknownFields allows arbitrary values within fields of this
+// type but also prevents any validation rules from reaching inside; its CEL
+// type is "object" or "message" with zero fields:
+// https://kubernetes.io/docs/reference/using-api/cel/#type-system-integration
 type SchemalessObject map[string]any
 
 // DeepCopy creates a new SchemalessObject by copying the receiver.

pkg/apis/postgres-operator.crunchydata.com/v1beta1/shared_types_test.go

@@ -16,6 +16,23 @@ import (
 	"sigs.k8s.io/yaml"
 )
 
+func TestDurationAsDuration(t *testing.T) {
+	t.Parallel()
+
+	v, err := NewDuration("2s")
+	assert.NilError(t, err)
+
+	// get the value
+	other := v.AsDuration()
+	assert.Equal(t, other.Duration, 2*time.Second,
+		"expected the same value as the original")
+
+	// change the copy
+	other.Duration = time.Hour
+	assert.Equal(t, v.AsDuration().Duration, 2*time.Second,
+		"expected no effect on the original value")
+}
+
 func TestDurationYAML(t *testing.T) {
 	t.Parallel()