Add comprehensive documentation for Declarative Validation by aaron-prindle · Pull Request #667 · kubernetes/contributor-site

aaron-prindle · 2026-02-25T17:40:31Z

Introduces a new documentation section for Declarative Validation (validation-gen) to k8s.dev (content/en/docs/code/declarative-validation/). This includes organized guides to help developers and API reviewers leverage DV efficiently in upcoming releases (v1.36+). This is related to this Slack conversation here:
https://kubernetes.slack.com/archives/C1J0BPD2M/p1771357063367439

The documentation is split across four pages:

Overview: Architecture, core concepts, and tooling.
Usage and Migration: Developer guide for both new APIs and migrating existing handwritten logic.
Validation Tags: A complete reference catalog of all supported +k8s: tags.
API Reviewers Guide: PR review guidelines, common pitfalls, and checklists.

These pages aim to explain declarative validation to API reviewers and developers in the goal of reducing the API review burden and broadening the adoption of declarative validation natively for new features.

k8s-ci-robot · 2026-02-25T17:40:40Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: aaron-prindle
Once this PR has been reviewed and has the lgtm label, please assign derekwaynecarr for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

content/en/docs/code/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Introduces a new documentation section for Declarative Validation (`validation-gen`) to k8s.dev (`content/en/docs/code/declarative-validation/`). This includes organized guides to help developers and API reviewers leverage DV efficiently in upcoming releases (v1.36+). The documentation is split into four categorized pages: - Overview: Architecture, core concepts, and tooling. - Usage and Migration: Developer guide for both new APIs and migrating existing handwritten logic. - Validation Tags: A complete reference catalog of all supported `+k8s:` tags. - API Reviewers Guide: PR review guidelines, common pitfalls, and checklists. These pages aim to reduce the API review burden and streamline the adoption of declarative validation natively for new features.

lmktfy

The only thing where I would insist on a change is the level 1 headings, which aren't needed. Lines like # Usage and Migration can just be removed.

If you drop them, I'd be happy to merge it as is. I have offered more feedback but it really doesn't block a merge.

lmktfy · 2026-02-26T17:48:58Z

content/en/docs/code/declarative-validation/_index.md

+  Overview and architecture of the Declarative Validation (`validation-gen`) project.
+---
+
+# Declarative Validation (`validation-gen`)


Suggested change

# Declarative Validation (`validation-gen`)

Here's why:

We only need a single title for the page.

Done! I have removed the redundant H1 titles across all the new pages (_index.md, api-reviewers-guide.md, and usage-and-migration.md)

lmktfy · 2026-02-26T17:49:34Z

content/en/docs/code/declarative-validation/_index.md

+
+This document provides an overview of the Declarative Validation project in Kubernetes, also known as `validation-gen`. This feature allows developers to define validation logic for native Kubernetes API types using Go comment tags (e.g., `+k8s:minimum=0`).
+
+## Architecture Overview


nit: headings within the page should be in sentence case (eg "Architecture overview")

Nice to have but doesn't block a merge.

Fixed for this case, will do a second pass for the other cases

lmktfy · 2026-02-26T17:50:53Z

content/en/docs/code/declarative-validation/_index.md

+*   [Usage and Migration](./usage-and-migration) - Learn how to use declarative validation for new APIs and how to migrate existing handwritten validation.
+*   [Validation Tags](./validation-tags) - See the full catalog of available validation tags.
+*   [API Reviewers Guide](./api-reviewers-guide) - Guidelines for API reviewers on reviewing PRs that use declarative validation.


Suggested change

* [Usage and Migration](./usage-and-migration) - Learn how to use declarative validation for new APIs and how to migrate existing handwritten validation.

* [Validation Tags](./validation-tags) - See the full catalog of available validation tags.

* [API Reviewers Guide](./api-reviewers-guide) - Guidelines for API reviewers on reviewing PRs that use declarative validation.

* [Usage and Migration](/docs/code/declarative-validation/usage-and-migration/) - Learn how to use declarative validation for new APIs and how to migrate existing handwritten validation.

* [Validation Tags](/docs/code/declarative-validation/validation-tags/) - See the full catalog of available validation tags.

* [API Reviewers Guide](/docs/code/declarative-validation/api-reviewers-guide/) - Guidelines for API reviewers on reviewing PRs that use declarative validation.

lmktfy · 2026-02-26T17:51:23Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+  Guidelines for API reviewers on reviewing PRs that use Declarative Validation for new APIs and migrations.
+---
+
+# API Reviewers Guide for Declarative Validation


Suggested change

# API Reviewers Guide for Declarative Validation

We only need a single title for the page. The theme adds one based on the front matter.

Removed the duplicate heading.

lmktfy · 2026-02-26T17:51:34Z

content/en/docs/code/declarative-validation/usage-and-migration.md

+  How to use Declarative Validation for new APIs and how to migrate existing handwritten validation.
+---
+
+# Usage and Migration


Suggested change

# Usage and Migration

We only need a single title for the page. The theme adds one based on the front matter.

lmktfy · 2026-02-26T17:57:21Z

content/en/docs/code/declarative-validation/validation-tags.md

+*   `DeclarativeValidationBeta`: (Beta, Default: `true`) Introduced in v1.36. This gate acts as the global safety switch for Beta-stage validation rules. It determines whether validation rules marked as `+k8s:beta` are enforced (authoritative) or remain in shadow mode. It has no effect if `DeclarativeValidation` is disabled.
+*   `DeclarativeValidationTakeover`: (Deprecated in v1.36). Previously used to determine whether declarative validation results were authoritative. It is no longer honored but can still be set during upgrades to prevent "gate not recognized" errors.
+
+**Default Behavior (Kubernetes v1.36+):**


If accepting the previous heading suggestion, try this:

Suggested change

**Default Behavior (Kubernetes v1.36+):**

### Default behavior (Kubernetes v1.36+) {#default-behavior}

lmktfy · 2026-02-26T17:57:54Z

content/en/docs/code/declarative-validation/validation-tags.md

+
+While primarily a feature impacting Kubernetes contributors and potentially developers of [extension API servers](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/), cluster administrators should understand its behavior, especially during its rollout phases.
+
+


Suggested change

## Rollout of declarative validation

Declarative validation is being rolled out gradually using a _validation lifecycle_ mechanism.

lmktfy · 2026-02-26T17:58:46Z

content/en/docs/code/declarative-validation/_index.md

+title: "Declarative Validation"
+weight: 50
+description: |
+  Overview and architecture of the Declarative Validation (`validation-gen`) project.


Suggested change

Overview and architecture of the Declarative Validation (`validation-gen`) project.

Overview and architecture of declarative API validation in Kubernetes.

I think these docs will be useful even after we have switched over.

lmktfy · 2026-02-26T18:00:35Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+
+# API Reviewers Guide for Declarative Validation
+
+Starting in Kubernetes v1.36, Declarative Validation (DV) is the recommended way to author API validation logic. This means in v1.36+ there will be k8s API PRs that need API review which use Declarative Validation which means API reviewers need to understand how to review DV PRs.  The review should be straightforward as DV's goal is to moving validation logic out of procedural Go code (`validation.go`) and into vetted declarative comment tags directly on the API types (`types.go`).


(nit)

Suggested change

Starting in Kubernetes v1.36, Declarative Validation (DV) is the recommended way to author API validation logic. This means in v1.36+ there will be k8s API PRs that need API review which use Declarative Validation which means API reviewers need to understand how to review DV PRs. The review should be straightforward as DV's goal is to moving validation logic out of procedural Go code (`validation.go`) and into vetted declarative comment tags directly on the API types (`types.go`).

Starting in Kubernetes v1.36, _Declarative Validation_ (DV) is the recommended way to author API validation logic.

This means that for v1.36 and later, there will be K8s API PRs that need API review and which use Declarative Validation.

As a result, API reviewers need to understand how to review PRs that include DV.

The review process should be straightforward as DV's goal is to moving validation logic out of procedural Go code (`validation.go`),

and into vetted declarative comment tags directly on the API types (`types.go`).

lmktfy · 2026-02-26T18:00:56Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+
+When a developer adds a new API or field and wants to use DV, the tags in `types.go` are the *only* validation logic. There should be no fallback handwritten code for these standard rules.
+
+### What to expect:


(nit)

Suggested change

### What to expect:

### What to expect

…rding tweaks

lmktfy

LGTM for docs & for contributor experience.

I would like someone representing either SIG Architecture or SIG API Machinery (no special need to cover both) to glance through this and confirm that nothing is obviously wrong. It all seems fine but I haven't actually looked at any of the specifics.

aaron-prindle · 2026-03-04T18:28:23Z

/cc @jpbetz

jpbetz · 2026-03-04T19:31:41Z

content/en/docs/code/declarative-validation/_index.md

+*   **Format Code**:
+    ```bash
+    hack/update-gofmt.sh
+    ```
+*   **Run All Verification Checks**:
+    ```bash
+    hack/verify-all.sh
+    ```


I recommend against re-documenting comment development tooling not specific to validation-gen here. Linking to other documentation may be more appropriate.

jpbetz · 2026-03-04T19:32:19Z

content/en/docs/code/declarative-validation/_index.md

+*   **Run `validate/*` Logic Tests**:
+    ```bash
+    go test ./staging/src/k8s.io/apimachinery/pkg/api/validate/...


How do we get access to or regenerate the tag documentation?

jpbetz · 2026-03-04T19:34:37Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+
+## Scenario A: New API Field (Authoritative DV)
+
+When a developer adds a new API or field and wants to use DV, the tags in `types.go` are the *only* validation logic. There should be no fallback handwritten code for these standard rules.


Suggested change

When a developer adds a new API or field and wants to use DV, the tags in `types.go` are the *only* validation logic. There should be no fallback handwritten code for these standard rules.

When a developer adds a new API or field and wants to use DV, the tags in `types.go` are the *only* validation logic. We *do not* require any handwritten validation code be authored for validation enforced by DV.

Maybe better? I'm looking for a way to explain this to people not deeply familiar with DV.

jpbetz · 2026-03-04T19:40:37Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+Before tags can be used, the developer must ensure code generation is enabled for the API package.
+```go
+// +k8s:validation-gen=TypeMeta
+// +k8s:validation-gen-input=k8s.io/api/<group>/<version>
+package v1
+```


Show the full file name please. We have internal and versioned APIs, and it's easy to mistakenly add this to the wrong one. We should state clearly that this belongs on version APIs, it might even be worth adding a warning here about making sure to add this to the correct doc.go file.

jpbetz · 2026-03-04T19:41:01Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+#### 2. `types.go` (The Single Source of Truth)
+The developer adds standard DV tags directly to the new field. 


Same here. Make sure to clarify that we put the tags on versioned types.

jpbetz · 2026-03-04T20:08:31Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+#### 2. `types.go` (The Single Source of Truth)
+The developer adds standard DV tags directly to the new field. 
+
+**Subresources:** If the API includes a `/status` subresource and validation is needed for it, the root type definition must include the `supportsSubresource` tag.


This is the most common type of subresource, but it's not the only type of subresource and the other types behave differently: https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md#subresources

Recommend clarify this.

jpbetz · 2026-03-04T20:09:17Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+type MyNewFeatureSpec struct {
+    // +required
+    // +k8s:required
+    // +k8s:maxLength=256
+    // +k8s:format=k8s-short-name
+    FeatureName string `json:"featureName"`
+}


I was expect a subresource example about Status to show a status stanza. It's super surprising that this example does not.

jpbetz · 2026-03-04T20:09:54Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+}
+```
+
+*   **Tags come from the official catalog.** Invented or misspelled tags are silently ignored.


Somehow link or provide a way for the reader to access the official catelog?

Invented or misspelled tags are silently ignored

True. But for documentation purposes, it might be worth explaining the significance this to a API author.

(I'd expect our linter to catch k8s: tag misspellings? Does it? Should it?)

jpbetz · 2026-03-04T20:11:18Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+```
+
+*   **Tags come from the official catalog.** Invented or misspelled tags are silently ignored.
+*   **Tags are applied across all API versions.** If the resource has both `v1` and `v1beta1`, tags must appear on both.


Suggested change

* **Tags are applied across all API versions.** If the resource has both `v1` and `v1beta1`, tags must appear on both.

* **Tags must be applied across all API versions.** If the resource has both `v1` and `v1beta1`, tags must appear on both.

jpbetz · 2026-03-04T20:11:40Z

content/en/docs/code/declarative-validation/api-reviewers-guide.md

+
+*   **Tags come from the official catalog.** Invented or misspelled tags are silently ignored.
+*   **Tags are applied across all API versions.** If the resource has both `v1` and `v1beta1`, tags must appear on both.
+*   **No handwritten `Validate*` functions for the same constraints.** The tags are authoritative.


This is not always true. We sometimes have both.

k8s-ci-robot requested review from derekwaynecarr and johnbelamaric February 25, 2026 17:40

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 25, 2026

aaron-prindle force-pushed the dv-docs branch from a2ab3fd to 67e35d3 Compare February 25, 2026 17:54

k8s-ci-robot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Feb 25, 2026

aaron-prindle force-pushed the dv-docs branch 2 times, most recently from 4bc9202 to 3959031 Compare February 26, 2026 00:18

aaron-prindle force-pushed the dv-docs branch from 3959031 to c06fe48 Compare February 26, 2026 01:54

lmktfy reviewed Feb 26, 2026

View reviewed changes

docs: address feedback - remove redundant H1s, update links, apply wo…

5f56e51

…rding tweaks

aaron-prindle force-pushed the dv-docs branch from 5f56e51 to c06fe48 Compare February 26, 2026 18:33

lmktfy reviewed Feb 26, 2026

View reviewed changes

k8s-ci-robot requested a review from jpbetz March 4, 2026 18:28

jpbetz reviewed Mar 4, 2026

View reviewed changes


		This document provides an overview of the Declarative Validation project in Kubernetes, also known as `validation-gen`. This feature allows developers to define validation logic for native Kubernetes API types using Go comment tags (e.g., `+k8s:minimum=0`).

		## Architecture Overview

	Default Behavior (Kubernetes v1.36+):
	### Default behavior (Kubernetes v1.36+) {#default-behavior}


		While primarily a feature impacting Kubernetes contributors and potentially developers of [extension API servers](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/), cluster administrators should understand its behavior, especially during its rollout phases.


	## Rollout of declarative validation

	Declarative validation is being rolled out gradually using a _validation lifecycle_ mechanism.

	Overview and architecture of the Declarative Validation (`validation-gen`) project.
	Overview and architecture of declarative API validation in Kubernetes.


		# API Reviewers Guide for Declarative Validation

		Starting in Kubernetes v1.36, Declarative Validation (DV) is the recommended way to author API validation logic. This means in v1.36+ there will be k8s API PRs that need API review which use Declarative Validation which means API reviewers need to understand how to review DV PRs. The review should be straightforward as DV's goal is to moving validation logic out of procedural Go code (`validation.go`) and into vetted declarative comment tags directly on the API types (`types.go`).

-Starting in Kubernetes v1.36, Declarative Validation (DV) is the recommended way to author API validation logic. This means in v1.36+ there will be k8s API PRs that need API review which use Declarative Validation which means API reviewers need to understand how to review DV PRs.  The review should be straightforward as DV's goal is to moving validation logic out of procedural Go code (`validation.go`) and into vetted declarative comment tags directly on the API types (`types.go`).
+Starting in Kubernetes v1.36, _Declarative Validation_ (DV) is the recommended way to author API validation logic.
+This means that for v1.36 and later, there will be K8s API PRs that need API review and which use Declarative Validation.
+As a result, API reviewers need to understand how to review PRs that include DV.
+The review process should be straightforward as DV's goal is to moving validation logic out of procedural Go code (`validation.go`),
+and into vetted declarative comment tags directly on the API types (`types.go`).


		When a developer adds a new API or field and wants to use DV, the tags in `types.go` are the only validation logic. There should be no fallback handwritten code for these standard rules.

		### What to expect:


		## Scenario A: New API Field (Authoritative DV)

		When a developer adds a new API or field and wants to use DV, the tags in `types.go` are the only validation logic. There should be no fallback handwritten code for these standard rules.

		#### 2. `types.go` (The Single Source of Truth)
		The developer adds standard DV tags directly to the new field.

	* Tags are applied across all API versions. If the resource has both `v1` and `v1beta1`, tags must appear on both.
	* Tags must be applied across all API versions. If the resource has both `v1` and `v1beta1`, tags must appear on both.

Conversation

aaron-prindle commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Feb 25, 2026

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

aaron-prindle commented Mar 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aaron-prindle commented Feb 25, 2026 •

edited

Loading