KEP-5073: Declarative Validation: Explain and update document with cross-field field reference validation information (#5363)

* KEP-5073: Declarative Validation: Explain and update document with cross-field field reference validation information

* address comments - update examples

* address comments - remove +k8s:reference

* address comments - add json field tags names to all examples

* address comments - fix listMapItem usage and show all type declarations

* address comments - remove subfield case from example

* address comments - remove bullet for conditional validation preference for virtual fields

* fix rebase, add back table entries

Author: aaron-prindle

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

@@ -62,6 +62,13 @@
     - [List Operations](#list-operations)
     - [Conditional Immutability](#conditional-immutability)
     - [Subresource-Specific Immutability](#subresource-specific-immutability)
+  - [Referencing Fields in Validation-Gen For Cross-Field Validation Rules](#referencing-fields-in-validation-gen-for-cross-field-validation-rules)
+    - [Field Reference Strategies](#field-reference-strategies)
+      - [Field Path Strategy](#field-path-strategy)
+      - [Virtual Field Strategy](#virtual-field-strategy)
+    - [Choosing Between Field Paths and Virtual Fields](#choosing-between-field-paths-and-virtual-fields)
+    - [Tag Placement and Hoisting](#tag-placement-and-hoisting)
+    - [Comprehensive Example:](#comprehensive-example)
   - [Subresources](#subresources)
     - [Status-Type Subresources](#status-type-subresources)
     - [Scale-Type Subresources](#scale-type-subresources)
@@ -748,6 +755,28 @@ The below rules are currently implemented or are very similar to an existing val
     N/A
    </td>
   </tr>
+  <tr>
+   <td style="background-color: null">
+    group membership (virtual field)
+   </td>
+   <td style="background-color: null">
+    `+k8s:memberOf(group: &lt;groupname>)`
+   </td>
+   <td style="background-color: null">
+    N/A
+   </td>
+  </tr>
+  <tr>
+   <td style="background-color: null">
+    list map item reference (virtual field)
+   </td>
+   <td style="background-color: null">
+    `+k8s:listMapItem(pairs: [[key,value],...])`
+   </td>
+   <td style="background-color: null">
+    N/A
+   </td>
+  </tr>
 </table>
 
 The below rules are not currently implemented in the [validation-gen prototype](https://github.com/jpbetz/kubernetes/tree/validation-gen) so the exact syntax is still WIP
@@ -1171,6 +1200,150 @@ type PodSpec struct {
     NodeName string `json:"nodeName,omitempty"`
 }
 ```
+### Referencing Fields in Validation-Gen For Cross-Field Validation Rules
+
+Cross-field validation refers to validation rules that depend on the values of multiple fields within a struct or across nested structs. Cross-field validations require a method for referencing additional fields from validation-gen IDL tags.
+
+#### Field Reference Strategies
+
+`validation-gen` supports two strategies for referencing fields in cross-field validations:
+
+1. **Field Paths** - Direct references using dot notation
+1. **Virtual Fields** - Identifier-based references for relationships
+
+##### Field Path Strategy
+
+Field paths use JSON field names with dot notation to reference other fields. 
+
+**When tags are placed on fields:**
+
+-  Field paths are relative to the parent typedef (allowing sibling access)
+-  No special `self` or `parent` keywords allowed
+-  Example: `siblingField` or `siblingStruct.childField`
+
+```go
+type Config struct {
+    MinValue int32 `json:"minValue"`
+    MaxValue int32 `json:"maxValue"`
+    
+    // +k8s:minimum(constraint: minValue)
+    // +k8s:maximum(constraint: maxValue)
+    Current int32 `json:"current"`
+}
+```
+
+**When tags are placed on the common ancestor typedef:**
+
+-  All references are to child fields
+
+```go
+// NOTE: this is illustrative - minimum/maximum tags do not support "target"
+// +k8s:minimum(target: current, constraint: minValue)
+// +k8s:maximum(target: current, constraint: maxValue)
+type Config struct {
+    MinValue int32 `json:"minValue"`
+    MaxValue int32 `json:"maxValue"`
+    Current int32 `json:"current"`
+}
+```
+
+##### Virtual Field Strategy
+
+Virtual fields provide identifier-based references for cross-field relationships. They are scoped to a GVK (GroupVersionKind) namespace.
+
+**Virtual Field Reference Tags:**
+
+-  `+k8s:memberOf(group: <groupname>)` - Adds field to a group for union/mutual exclusion validation
+-  `+k8s:listMapItem(pairs: [[key,value],...])` - References specific items by key value in listType=map lists where the key(s) must include all of the list maps's keys
+
+```go
+type Config struct {
+    // +k8s:listType=map
+    // +k8s:listMapKey=type
+    // +k8s:union(union: terminalStatus)
+    // +k8s:listMapItem([["type","Succeeded"]])=+k8s:memberOf(group: terminalStatus)
+    // +k8s:listMapItem([["type","Failed"]])=+k8s:memberOf(group: terminalStatus)
+    Conditions []Condition `json:"conditions"`
+}
+
+type Condition struct {
+    Type               string `json:"type"`
+    Status             string `json:"status"`
+}
+```
+
+**Virtual Field Scope:**
+
+-  Virtual fields are scoped to the given GVK. The logical namespace for virtual fields is their GVK. For example, the virtual field names in apps/v1/Deployment are internally namespaced as apps/v1/Deployment:minReplicas, apps/v1/Deployment:maxReplicas, etc. However, within the same GVK, these can be referenced using just their simple names (minReplicas, maxReplicas) without the namespace prefix.
+-  **Cross-GVK references are NOT supported**
+    -  This mainly impacts any ObjectMeta name and generateName validation, which MUST be done using subfield and/or field-paths, not with virtual field references.
+
+#### Choosing Between Field Paths and Virtual Fields
+
+**Use Field Paths when:**
+
+-  Making simple references to sibling or child fields
+-  All referenced fields are accessible via dot notation
+
+**Use Virtual Fields when:**
+
+-  Implementing group-based rules (union validations, etc.)
+-  Referencing specific items in listType=map
+
+#### Tag Placement and Hoisting
+
+Cross-field validation tags can be placed on either tag location depending on what the tag supports:
+
+1. **On fields directly** - More intuitive but requires implicit hoisting to common ancestor
+1. **On common ancestor typedef** - Explicit placement where validation actually occurs
+
+All cross-field validations are ultimately hoisted to execute at the common ancestor level to ensure proper access to all referenced fields during validation.
+
+#### Comprehensive Example:
+
+```go
+type Config struct {
+    MinValue int `json:"minValue"`
+    MaxCpu int `json:"maxCpu"`
+    MaxThreshold int `json:"maxThreshold"`
+    
+    // +k8s:minimum(constraint: minValue)
+    // +k8s:maximum(constraint: limits.maxValue)
+    Current int `json:"current"`
+    
+    Limits LimitConfig `json:"limits"`
+    
+    Settings SettingsConfig `json:"settings"`
+    
+    // +k8s:eachVal=+k8s:maximum(constraint: maxThreshold)
+    Thresholds []int `json:"thresholds"`
+    
+    // +k8s:listType=map
+    // +k8s:listMapKey=type
+    // +k8s:union(union: terminalStatus)
+    // +k8s:listMapItem([["type","Succeeded"]])=+k8s:memberOf(group: terminalStatus)
+    // +k8s:listMapItem([["type","Failed"]])=+k8s:memberOf(group: terminalStatus)
+    Conditions []Condition `json:"conditions"`
+}
+
+type LimitConfig struct {
+    MaxValue int `json:"maxValue"`
+}
+
+type SettingsConfig struct {
+    Resources ResourceConfig `json:"resources"`
+}
+
+type ResourceConfig struct {
+    Cpu int `json:"cpu"`
+}
+
+type Condition struct {
+    Type               string `json:"type"`
+    Status             string `json:"status"`
+}
+```
+
 
 ### Subresources