From d0f482129da78923527b796837a1199beb48a3cd Mon Sep 17 00:00:00 2001
From: Lalit Chauhan <lalitchauhan@google.com>
Date: Thu, 7 Aug 2025 22:01:46 +0000
Subject: [PATCH] Add stability level in the tags doc.

---
 .../cmd/validation-gen/validators/each.go     | 14 +++++----
 .../cmd/validation-gen/validators/enum.go     | 12 ++++----
 .../cmd/validation-gen/validators/equality.go |  1 +
 .../cmd/validation-gen/validators/format.go   |  7 +++--
 .../validation-gen/validators/immutable.go    |  7 +++--
 .../cmd/validation-gen/validators/item.go     |  5 ++--
 .../cmd/validation-gen/validators/limits.go   | 14 +++++----
 .../cmd/validation-gen/validators/list.go     | 30 +++++++++++--------
 .../cmd/validation-gen/validators/opaque.go   |  5 ++--
 .../cmd/validation-gen/validators/options.go  |  3 +-
 .../cmd/validation-gen/validators/registry.go |  8 +++++
 .../cmd/validation-gen/validators/required.go |  3 ++
 .../cmd/validation-gen/validators/subfield.go |  7 +++--
 .../cmd/validation-gen/validators/testing.go  |  5 ++--
 .../cmd/validation-gen/validators/union.go    | 14 +++++----
 .../cmd/validation-gen/validators/update.go   |  7 +++--
 .../validation-gen/validators/validators.go   | 16 ++++++++++
 .../validation-gen/validators/zeroorone.go    |  9 +++---
 18 files changed, 108 insertions(+), 59 deletions(-)

diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/each.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/each.go
index 5b5f182449e..4961f46d26d 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/each.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/each.go
@@ -225,9 +225,10 @@ func (evtv eachValTagValidator) getMapValidations(t *types.Type, validations Val
 
 func (evtv eachValTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         evtv.TagName(),
-		Scopes:      evtv.ValidScopes().UnsortedList(),
-		Description: "Declares a validation for each value in a map or list.",
+		Tag:            evtv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         evtv.ValidScopes().UnsortedList(),
+		Description:    "Declares a validation for each value in a map or list.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<validation-tag>",
 			Docs:        "The tag to evaluate for each value.",
@@ -306,9 +307,10 @@ func ForEachKey(_ *field.Path, t *types.Type, fn FunctionGen) (Validations, erro
 
 func (ektv eachKeyTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         ektv.TagName(),
-		Scopes:      ektv.ValidScopes().UnsortedList(),
-		Description: "Declares a validation for each value in a map or list.",
+		Tag:            ektv.TagName(),
+		Scopes:         ektv.ValidScopes().UnsortedList(),
+		StabilityLevel: Alpha,
+		Description:    "Declares a validation for each value in a map or list.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<validation-tag>",
 			Docs:        "The tag to evaluate for each key.",
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/enum.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/enum.go
index 0ab3dc12fc0..ffc7ff27d10 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/enum.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/enum.go
@@ -61,8 +61,9 @@ func (*enumExcludeTagValidator) GetValidations(_ Context, _ codetags.Tag) (Valid
 
 func (eetv *enumExcludeTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:    eetv.TagName(),
-		Scopes: eetv.ValidScopes().UnsortedList(),
+		Tag:            eetv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         eetv.ValidScopes().UnsortedList(),
 		Description: `Indicates that an constant value is not part of an enum, even if the constant's type is tagged with k8s:enum.
 May be conditionally excluded via +k8s:ifEnabled(Option)=+k8s:enumExclude or +k8s:ifDisabled(Option)=+k8s:enumExclude.
 If multiple +k8s:ifEnabled/+k8s:ifDisabled tags are used, the value is excluded if any of the exclude conditions are met.`,
@@ -192,9 +193,10 @@ func (etv *enumTagValidator) GetValidations(context Context, _ codetags.Tag) (Va
 
 func (etv *enumTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         etv.TagName(),
-		Scopes:      etv.ValidScopes().UnsortedList(),
-		Description: "Indicates that a string type is an enum. All constant values of this type are considered values in the enum unless excluded using +k8s:enumExclude.",
+		Tag:            etv.TagName(),
+		StabilityLevel: Beta,
+		Scopes:         etv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that a string type is an enum. All constant values of this type are considered values in the enum unless excluded using +k8s:enumExclude.",
 	}
 }
 
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/equality.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/equality.go
index d4083f2e726..005213b4667 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/equality.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/equality.go
@@ -98,6 +98,7 @@ func (v neqTagValidator) GetValidations(context Context, tag codetags.Tag) (Vali
 func (v neqTagValidator) Docs() TagDoc {
 	return TagDoc{
 		Tag:              v.TagName(),
+		StabilityLevel:   Alpha,
 		Scopes:           v.ValidScopes().UnsortedList(),
 		Description:      "Verifies the field's value is not equal to a specific disallowed value. Supports string, integer, and boolean types.",
 		PayloadsRequired: true,
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/format.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/format.go
index aa6612f826d..b147ce7635f 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/format.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/format.go
@@ -113,9 +113,10 @@ func getFormatValidationFunction(format string) (FunctionGen, error) {
 
 func (ftv formatTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         ftv.TagName(),
-		Scopes:      ftv.ValidScopes().UnsortedList(),
-		Description: "Indicates that a string field has a particular format.",
+		Tag:            ftv.TagName(),
+		StabilityLevel: Beta,
+		Scopes:         ftv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that a string field has a particular format.",
 		Payloads: []TagPayloadDoc{{ // Keep this list alphabetized.
 			Description: "k8s-ip",
 			Docs:        "This field holds an IPv4 or IPv6 address value. IPv4 octets may have leading zeros.",
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/immutable.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/immutable.go
index c4a94154f65..82cdf4d2df5 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/immutable.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/immutable.go
@@ -58,8 +58,9 @@ func (immutableTagValidator) GetValidations(context Context, _ codetags.Tag) (Va
 
 func (itv immutableTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         itv.TagName(),
-		Scopes:      itv.ValidScopes().UnsortedList(),
-		Description: "Indicates that a field may not be updated.",
+		Tag:            itv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         itv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that a field may not be updated.",
 	}
 }
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/item.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/item.go
index b6c9f9b035f..78f1adfbdca 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/item.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/item.go
@@ -248,8 +248,9 @@ func parseTypedValue(value string, argType codetags.ArgType) (any, codetags.Valu
 
 func (itv itemTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:    itv.TagName(),
-		Scopes: itv.ValidScopes().UnsortedList(),
+		Tag:            itv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         itv.ValidScopes().UnsortedList(),
 		Description: "Declares a validation for an item of a slice declared as a +k8s:listType=map. " +
 			"The item to match is declared by providing field-value pair arguments. All key fields must be specified.",
 		Usage: "+k8s:item(stringKey: \"value\", intKey: 42, boolKey: true)=<validation-tag>",
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/limits.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/limits.go
index 4992e79400e..e1018328d79 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/limits.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/limits.go
@@ -81,9 +81,10 @@ func (maxItemsTagValidator) GetValidations(context Context, tag codetags.Tag) (V
 
 func (mitv maxItemsTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         mitv.TagName(),
-		Scopes:      mitv.ValidScopes().UnsortedList(),
-		Description: "Indicates that a list has a limit on its size.",
+		Tag:            mitv.TagName(),
+		StabilityLevel: Beta,
+		Scopes:         mitv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that a list has a limit on its size.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<non-negative integer>",
 			Docs:        "This list must be no more than X items long.",
@@ -130,9 +131,10 @@ func (minimumTagValidator) GetValidations(context Context, tag codetags.Tag) (Va
 
 func (mtv minimumTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         mtv.TagName(),
-		Scopes:      mtv.ValidScopes().UnsortedList(),
-		Description: "Indicates that a numeric field has a minimum value.",
+		Tag:            mtv.TagName(),
+		StabilityLevel: Beta,
+		Scopes:         mtv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that a numeric field has a minimum value.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<integer>",
 			Docs:        "This field must be greater than or equal to x.",
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/list.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/list.go
index 4af73a195d4..11e8b2f6b56 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/list.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/list.go
@@ -171,9 +171,10 @@ func (lttv listTypeTagValidator) GetValidations(context Context, tag codetags.Ta
 
 func (lttv listTypeTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         lttv.TagName(),
-		Scopes:      lttv.ValidScopes().UnsortedList(),
-		Description: "Declares a list field's semantic type and ownership behavior. atomic: single ownership, set: shared ownership with uniqueness, map: shared ownership with key-based uniqueness.",
+		Tag:            lttv.TagName(),
+		StabilityLevel: Beta,
+		Scopes:         lttv.ValidScopes().UnsortedList(),
+		Description:    "Declares a list field's semantic type and ownership behavior. atomic: single ownership, set: shared ownership with uniqueness, map: shared ownership with key-based uniqueness.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<type>",
 			Docs:        "atomic | map | set",
@@ -233,9 +234,10 @@ func (lmktv listMapKeyTagValidator) GetValidations(context Context, tag codetags
 
 func (lmktv listMapKeyTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         lmktv.TagName(),
-		Scopes:      lmktv.ValidScopes().UnsortedList(),
-		Description: "Declares a named sub-field of a list's value-type to be part of the list-map key.",
+		Tag:            lmktv.TagName(),
+		StabilityLevel: Beta,
+		Scopes:         lmktv.ValidScopes().UnsortedList(),
+		Description:    "Declares a named sub-field of a list's value-type to be part of the list-map key.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<field-json-name>",
 			Docs:        "The name of the field.",
@@ -301,9 +303,10 @@ func (utv uniqueTagValidator) GetValidations(context Context, tag codetags.Tag)
 
 func (utv uniqueTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         utv.TagName(),
-		Scopes:      utv.ValidScopes().UnsortedList(),
-		Description: "Declares that a list field's elements are unique. This tag can be used with listType=atomic to add uniqueness constraints, or independently to specify uniqueness semantics.",
+		Tag:            utv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         utv.ValidScopes().UnsortedList(),
+		Description:    "Declares that a list field's elements are unique. This tag can be used with listType=atomic to add uniqueness constraints, or independently to specify uniqueness semantics.",
 		Payloads: []TagPayloadDoc{{
 			Description: "<type>",
 			Docs:        "map | set",
@@ -350,10 +353,11 @@ func (cutv customUniqueTagValidator) GetValidations(context Context, tag codetag
 
 func (cutv customUniqueTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         cutv.TagName(),
-		Scopes:      cutv.ValidScopes().UnsortedList(),
-		Description: "Indicates that uniqueness validation for this list is implemented via custom, handwritten validation. This disables generation of uniqueness validation for this list.",
-		Payloads:    nil,
+		Tag:            cutv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         cutv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that uniqueness validation for this list is implemented via custom, handwritten validation. This disables generation of uniqueness validation for this list.",
+		Payloads:       nil,
 	}
 	return doc
 }
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/opaque.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/opaque.go
index 45b2ea4bba2..2b4124be68c 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/opaque.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/opaque.go
@@ -47,8 +47,9 @@ func (opaqueTypeTagValidator) GetValidations(_ Context, _ codetags.Tag) (Validat
 
 func (opaqueTypeTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:    opaqueTypeTagName,
-		Scopes: []Scope{ScopeField},
+		Tag:            opaqueTypeTagName,
+		StabilityLevel: Alpha,
+		Scopes:         []Scope{ScopeField},
 		Description: "Indicates that any validations declared on the referenced type will be ignored. " +
 			"If a referenced type's package is not included in the generator's current " +
 			"flags, this tag must be set, or code generation will fail (preventing silent " +
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/options.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/options.go
index 2de800b9d8b..71037240764 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/options.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/options.go
@@ -80,7 +80,8 @@ func (itv ifTagValidator) GetValidations(context Context, tag codetags.Tag) (Val
 
 func (itv ifTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag: itv.TagName(),
+		Tag:            itv.TagName(),
+		StabilityLevel: Alpha,
 		Args: []TagArgDoc{{
 			Description: "<option>",
 			Type:        codetags.ArgTypeString,
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/registry.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/registry.go
index c8b29a8e1ad..fa37bab8b8a 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/registry.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/registry.go
@@ -58,6 +58,14 @@ func (reg *registry) addTagValidator(tv TagValidator) {
 	if _, exists := globalRegistry.tagValidators[name]; exists {
 		panic(fmt.Sprintf("tag %q was registered twice", name))
 	}
+	switch level := tv.Docs().StabilityLevel; level {
+	case Alpha, Beta, Stable:
+		// valid
+	case "":
+		panic(fmt.Sprintf("tag %q is missing stability level", name))
+	default:
+		panic(fmt.Sprintf("tag %q has invalid stability level %q", name, level))
+	}
 	globalRegistry.tagValidators[name] = tv
 }
 
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/required.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/required.go
index 9a1b1583d67..a6546c46b17 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/required.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/required.go
@@ -309,10 +309,13 @@ func (rtv requirednessTagValidator) Docs() TagDoc {
 
 	switch rtv.mode {
 	case requirednessRequired:
+		doc.StabilityLevel = Beta
 		doc.Description = "Indicates that a field must be specified by clients."
 	case requirednessOptional:
+		doc.StabilityLevel = Beta
 		doc.Description = "Indicates that a field is optional to clients."
 	case requirednessForbidden:
+		doc.StabilityLevel = Alpha
 		doc.Description = "Indicates that a field may not be specified."
 	default:
 		panic(fmt.Sprintf("unknown requiredness mode: %q", rtv.mode))
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/subfield.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/subfield.go
index dcdf73df7ae..fdb477cf60d 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/subfield.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/subfield.go
@@ -133,9 +133,10 @@ func (stv subfieldTagValidator) GetValidations(context Context, tag codetags.Tag
 
 func (stv subfieldTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:         stv.TagName(),
-		Scopes:      stv.ValidScopes().UnsortedList(),
-		Description: "Declares a validation for a subfield of a struct.",
+		Tag:            stv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         stv.ValidScopes().UnsortedList(),
+		Description:    "Declares a validation for a subfield of a struct.",
 		Args: []TagArgDoc{{
 			Description: "<field-json-name>",
 			Type:        codetags.ArgTypeString,
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/testing.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/testing.go
index fc9dafd705a..8471c34630d 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/testing.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/testing.go
@@ -126,8 +126,9 @@ func (fixedResultTagValidator) toFixedResultArgs(in codetags.Tag) (fixedResultAr
 
 func (frtv fixedResultTagValidator) Docs() TagDoc {
 	doc := TagDoc{
-		Tag:    frtv.TagName(),
-		Scopes: frtv.ValidScopes().UnsortedList(),
+		Tag:            frtv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         frtv.ValidScopes().UnsortedList(),
 	}
 	doc.PayloadsType = codetags.ValueTypeString
 	if frtv.error {
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/union.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/union.go
index 221fde89b7c..193579fce4e 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/union.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/union.go
@@ -116,9 +116,10 @@ func (udtv unionDiscriminatorTagValidator) GetValidations(context Context, tag c
 
 func (udtv unionDiscriminatorTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         udtv.TagName(),
-		Scopes:      udtv.ValidScopes().UnsortedList(),
-		Description: "Indicates that this field is the discriminator for a union.",
+		Tag:            udtv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         udtv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that this field is the discriminator for a union.",
 		Args: []TagArgDoc{{
 			Name:        "union",
 			Description: "<string>",
@@ -154,9 +155,10 @@ func (umtv unionMemberTagValidator) GetValidations(context Context, tag codetags
 
 func (umtv unionMemberTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         umtv.TagName(),
-		Scopes:      umtv.ValidScopes().UnsortedList(),
-		Description: "Indicates that this field is a member of a union.",
+		Tag:            umtv.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         umtv.ValidScopes().UnsortedList(),
+		Description:    "Indicates that this field is a member of a union.",
 		Args: []TagArgDoc{{
 			Name:        "union",
 			Description: "<string>",
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/update.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/update.go
index 973a90f018d..056f9a81b5c 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/update.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/update.go
@@ -124,9 +124,10 @@ func constraintName(c validate.UpdateConstraint) string {
 
 func (utc updateTagCollector) Docs() TagDoc {
 	return TagDoc{
-		Tag:          utc.TagName(),
-		Scopes:       utc.ValidScopes().UnsortedList(),
-		PayloadsType: codetags.ValueTypeString,
+		Tag:            utc.TagName(),
+		StabilityLevel: Alpha,
+		Scopes:         utc.ValidScopes().UnsortedList(),
+		PayloadsType:   codetags.ValueTypeString,
 		Description: "Provides constraints on the allowed update operations of a field. " +
 			"Currently supports non-list and non-map fields only. " +
 			"Constraints: NoSet (prevents unset->set transitions), NoUnset (prevents set->unset transitions), " +
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/validators.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/validators.go
index 7737de49339..1aa4f3c8db0 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/validators.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/validators.go
@@ -247,10 +247,26 @@ type ListSelectorTerm struct {
 	Value any
 }
 
+// StabilityLevel indicates the stability of a validation tag.
+type StabilityLevel string
+
+const (
+	// Alpha indicates that a tag's semantics may change in the future.
+	Alpha StabilityLevel = "Alpha"
+	// Beta indicates that a tag's semantics will remain unchanged for the
+	// foreseeable future. This is used for soaking tags before qualifying to stable.
+	Beta StabilityLevel = "Beta"
+	// Stable indicates that a tag's semantics will remain unchanged for the
+	// foreseeable future.
+	Stable StabilityLevel = "Stable"
+)
+
 // TagDoc describes a comment-tag and its usage.
 type TagDoc struct {
 	// Tag is the tag name, without the leading '+'.
 	Tag string
+	// StabilityLevel is the stability level of the tag.
+	StabilityLevel StabilityLevel
 	// Args lists any arguments this tag might take.
 	Args []TagArgDoc
 	// Usage is how the tag is used, including arguments.
diff --git a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/zeroorone.go b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/zeroorone.go
index 3c37963b2da..cfad1ef6fba 100644
--- a/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/zeroorone.go
+++ b/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/zeroorone.go
@@ -94,10 +94,11 @@ func (zmtv zeroOrOneOfMemberTagValidator) GetValidations(context Context, tag co
 
 func (zmtv zeroOrOneOfMemberTagValidator) Docs() TagDoc {
 	return TagDoc{
-		Tag:         zmtv.TagName(),
-		Scopes:      zmtv.ValidScopes().UnsortedList(),
-		Description: "Indicates that this field is a member of a zero-or-one-of union.",
-		Docs:        "A zero-or-one-of union allows at most one member to be set. Unlike regular unions, having no members set is valid.",
+		Tag:            zmtv.TagName(),
+		Scopes:         zmtv.ValidScopes().UnsortedList(),
+		StabilityLevel: Alpha,
+		Description:    "Indicates that this field is a member of a zero-or-one-of union.",
+		Docs:           "A zero-or-one-of union allows at most one member to be set. Unlike regular unions, having no members set is valid.",
 		Args: []TagArgDoc{{
 			Name:        "union",
 			Description: "<string>",