docs: add documentation for adding a new API fields with validation using DV tags only and testing by aaron-prindle · Pull Request #8906 · kubernetes/community

aaron-prindle · 2026-03-17T17:25:16Z

This updates api_changes.md with a prescriptive section for the CUJ: “add a new API field and validate it with declarative validation”. It documents the DV plumbing prerequisites, DV tag authoring, feature gate and strategy wiring, codegen checks, status subresource handling, current workarounds like +k8s:validation-gen-nolint, and copy-paste snippets + testing guidance for declarative_validation_test.go and strategy_test.go.

Which issue(s) this PR fixes:

Fixes #
N/A

aaron-prindle · 2026-03-17T17:41:51Z

/cc @yongruilin @lalitc375

aaron-prindle · 2026-03-17T19:15:38Z

/assign @thockin

yongruilin · 2026-03-17T20:11:50Z

contributors/devel/sig-architecture/api_changes.md

+rule, prefer handwritten validation for that field rather than mixing DV and
+handwritten validation for the same field.


Do we prefer handwritten if part of the validation on the same field can be DV?

Yes, my understanding from our last sync meeting on Friday is that API reviewers want new APIs fields validation to be all DV or no DV for the validations of a given new field.

Updated the text to be:

If DV can cover some of the new field's checks but cannot cover all of them,
prefer handwritten validation for that field rather than splitting one field's
checks between DV and handwritten validation.

yongruilin · 2026-03-17T20:18:19Z

contributors/devel/sig-architecture/api_changes.md


 While the goal is to express as much validation declaratively as possible, some complex or validation rules might still require manual implementation in `validation.go`.

+#### Adding a new API field with DV-native validation


It is straightforward for adding a "new API type". But a bit tricky when it comes to a new API field:
If this type already migrated some existing fields to DV. Do we still support? Once the strategy add the WithDeclarativeEnforcement(), non-prefixed tag would become authoritative and handwritten counterpart needs to be deleted; otherwise, the migrated fields need to add the k8s:beta(or alpha?) prefix to enable explicitly shadowing.

I clarified the scope of this section with an additional small paragraph around this

This guidance assumes the API type is plumbed for declarative
validation. If the type already has existing DV migrated/shadowed fields (+k8s:alpha/+k8s:beta) and still relies on fields w/ handwritten validation and/or shadowed DV, those older fields can continue to
exist as-is, but do not introduce that split for the new field covered by this
section.

yongruilin · 2026-03-17T20:26:03Z

contributors/devel/sig-architecture/api_changes.md

+* gate off, field specified
+* gate off, field omitted
+* gate off, old value unchanged on update
+* gate off, old value changed on update


The last case, gate off, old value changed on update, we should have a fobidden error right? I think we can extend this a bit about what should be the expected test result.

I updated the test guidance to make the expected result explicit. Now is a table:

Case Expected result

gate on, field specified Allowed if the value is valid.

gate on, field omitted Allowed.

gate on, invalid value specified Rejected with the field's normal validation error, such as NotSupported, Invalid, TooLong, or TooMany.

gate off, field specified Rejected. With the standard ifDisabled(...)=+k8s:forbidden pattern, expect a forbidden error.

gate off, field omitted Allowed.

gate off, old value unchanged on update Allowed due to ratcheting.

gate off, old value changed on update Rejected. With the standard ifDisabled(...)=+k8s:forbidden pattern, expect a forbidden error because the update is attempting to write a disabled field value.

aaron-prindle · 2026-03-24T15:45:57Z

/area api-validation

k8s-ci-robot · 2026-03-24T15:46:02Z

@aaron-prindle: The label(s) area/api-validation cannot be applied, because the repository doesn't have them.

Details

In response to this:

/area api-validation

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

aaron-prindle · 2026-03-26T21:11:00Z

Addressed the initial review comments there, PTAL the updated docs @yongruilin

yongruilin · 2026-04-01T22:46:50Z

/lgtm

k8s-ci-robot · 2026-04-02T15:27:13Z

New changes are detected. LGTM label has been removed.

k8s-ci-robot · 2026-04-02T15:27:17Z

[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 ask for approval from thockin. 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:

contributors/devel/sig-architecture/OWNERS

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

…sing DV tags only and testing

liggitt · 2026-04-02T18:45:10Z

contributors/devel/sig-architecture/api_changes.md

+  // +k8s:ifEnabled("Frobber2D")=+k8s:optional
+  // +k8s:ifEnabled("Frobber2D")=+k8s:maximum=128


feedback from sig-arch conversation, we wouldn't make validation conditional like this ... if there is data in the field, we validate it

Suggested change

// +k8s:ifEnabled("Frobber2D")=+k8s:optional

// +k8s:ifEnabled("Frobber2D")=+k8s:maximum=128

// +k8s:optional

// +k8s:maximum=128

Then here it is. And whether to have +k8s:forbidden depends on whether it is really the case for this specific new field.

liggitt · 2026-04-02T18:56:53Z

contributors/devel/sig-architecture/api_changes.md

+  // +featureGate=Frobber2D
+  // +optional
+  // +k8s:optional
+  // +k8s:ifDisabled("Frobber2D")=+k8s:forbidden


feedback from sig-arch conversation, this belongs more to the feature-gate-informed wipe (or forbid) pass done before getting to validation

…g the feature gates for validation but also calling out how you could for special cases

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Mar 17, 2026

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

aaron-prindle force-pushed the dv-adding-a-new-field-docs-v2 branch from d11a786 to bf0efac Compare March 17, 2026 17:41

k8s-ci-robot requested review from lalitc375 and yongruilin March 17, 2026 17:41

k8s-ci-robot assigned thockin Mar 17, 2026

yongruilin reviewed Mar 17, 2026

View reviewed changes

aaron-prindle force-pushed the dv-adding-a-new-field-docs-v2 branch 2 times, most recently from 962fe20 to 78e1c1a Compare March 18, 2026 05:10

k8s-ci-robot assigned yongruilin Apr 1, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 1, 2026

aaron-prindle force-pushed the dv-adding-a-new-field-docs-v2 branch from 78e1c1a to d4e3229 Compare April 2, 2026 15:27

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 2, 2026

aaron-prindle force-pushed the dv-adding-a-new-field-docs-v2 branch from d4e3229 to 91932a6 Compare April 2, 2026 15:27

docs: add documentation for adding a new API fields with validation u…

6580962

…sing DV tags only and testing

aaron-prindle force-pushed the dv-adding-a-new-field-docs-v2 branch from 91932a6 to 6580962 Compare April 2, 2026 15:46

liggitt reviewed Apr 2, 2026

View reviewed changes

address feedback - sig-arch feedback related to recommending not usin…

3fc5f11

…g the feature gates for validation but also calling out how you could for special cases

		rule, prefer handwritten validation for that field rather than mixing DV and
		handwritten validation for the same field.


		While the goal is to express as much validation declaratively as possible, some complex or validation rules might still require manual implementation in `validation.go`.

		#### Adding a new API field with DV-native validation

Case	Expected result
gate on, field specified	Allowed if the value is valid.
gate on, field omitted	Allowed.
gate on, invalid value specified	Rejected with the field's normal validation error, such as `NotSupported`, `Invalid`, `TooLong`, or `TooMany`.
gate off, field specified	Rejected. With the standard `ifDisabled(...)=+k8s:forbidden` pattern, expect a forbidden error.
gate off, field omitted	Allowed.
gate off, old value unchanged on update	Allowed due to ratcheting.
gate off, old value changed on update	Rejected. With the standard `ifDisabled(...)=+k8s:forbidden` pattern, expect a forbidden error because the update is attempting to write a disabled field value.

		// +k8s:ifEnabled("Frobber2D")=+k8s:optional
		// +k8s:ifEnabled("Frobber2D")=+k8s:maximum=128

Conversation

aaron-prindle commented Mar 17, 2026

Uh oh!

aaron-prindle commented Mar 17, 2026

Uh oh!

aaron-prindle commented Mar 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

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!

aaron-prindle commented Mar 24, 2026

Uh oh!

k8s-ci-robot commented Mar 24, 2026

Uh oh!

aaron-prindle commented Mar 26, 2026

Uh oh!

yongruilin commented Apr 1, 2026

Uh oh!

k8s-ci-robot commented Apr 2, 2026

Uh oh!

k8s-ci-robot commented Apr 2, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aaron-prindle Mar 18, 2026 •

edited

Loading

aaron-prindle Mar 18, 2026 •

edited

Loading