requiredfields/optionalfields: false positive on metav1.Time and corev1.LocalObjectReference with omitzero

[muraee]

Description

The requiredfields and optionalfields analyzers produce false positives for fields using well-known Kubernetes types like metav1.Time and corev1.LocalObjectReference when paired with omitzero.

Example

type EncryptionMigrationHistory struct {
	// startedTime is when the rotation was initiated.
	// +required
	StartedTime metav1.Time `json:"startedTime,omitzero"`
	// completionTime is when the rotation finished.
	// +optional
	CompletionTime metav1.Time `json:"completionTime,omitzero"`
}

type AESCBCKeyStatus struct {
	// secret is a reference to the Secret containing the key.
	// +required
	Secret corev1.LocalObjectReference `json:"secret,omitzero"`
}

Lint output

requiredfields: field EncryptionMigrationHistory.StartedTime has a valid zero value ({}), but the validation is not complete (e.g. min properties/adding required fields). The field should be a pointer to allow the zero value to be set. If the zero value is not a valid use case, complete the validation and remove the pointer.

optionalfields: field EncryptionMigrationHistory.CompletionTime has a valid zero value ({}), but the validation is not complete (e.g. min properties/adding required fields). The field should be a pointer to allow the zero value to be set. If the zero value is not a valid use case, complete the validation and remove the pointer.

requiredfields: field AESCBCKeyStatus.Secret has a valid zero value ({}), but the validation is not complete (e.g. min properties/adding required fields). The field should be a pointer to allow the zero value to be set. If the zero value is not a valid use case, complete the validation and remove the pointer.

Why this is a false positive

The linter inspects the external struct via Go's type system, counts non-omitted fields, finds zero (because all internal fields use omitempty/omitzero), and concludes the zero value {} is "valid but validation is incomplete."

However, for well-known Kubernetes types like metav1.Time (which wraps time.Time), a zero value is never a meaningful user choice — it represents the Go zero, not a valid timestamp. Making these fields pointers solely to distinguish "zero time" from "unset" is unnecessary when omitzero already handles omission correctly.

Similarly, corev1.LocalObjectReference with a single Name field that has omitempty — the zero value {} is not a valid object reference.

Suggested fix

The linter should recognize well-known Kubernetes API types (e.g., metav1.Time, metav1.Duration, corev1.LocalObjectReference, corev1.ObjectReference, resource.Quantity) as types where the zero value is not a meaningful user input, and skip the "should be a pointer" suggestion for them. Alternatively, providing a configuration option to allowlist specific external types would also work.

Version

sigs.k8s.io/kube-api-linter v0.0.0-20260518104151-5ebe05f9440b

[muraee]

Additional false positive: omitempty demanded on struct fields that already have omitzero

Related to the same root cause, the requiredfields and optionalfields analyzers also report that these struct fields "should have the omitempty tag" — but omitempty is a no-op for non-pointer structs in Go's encoding/json. The correct tag for omitting zero-value structs is omitzero (available since Go 1.24), which these fields already use.

Example

// +required
Secret corev1.LocalObjectReference `json:"secret,omitzero"`

// +required
StartedTime metav1.Time `json:"startedTime,omitzero"`

// +optional
CompletionTime metav1.Time `json:"completionTime,omitzero"`

Additional lint output

requiredfields: field AESCBCKeyStatus.Secret should have the omitempty tag.
requiredfields: field EncryptionMigrationHistory.StartedTime should have the omitempty tag.
optionalfields: field EncryptionMigrationHistory.CompletionTime should have the omitempty tag.

Why this is incorrect

Adding omitempty alongside omitzero on a struct field is harmless but misleading — it suggests omitempty does something, when in fact only omitzero controls struct omission. The linter should recognize that omitzero already satisfies the "omit when zero" requirement for struct-typed fields and not additionally demand omitempty.

[JoelSpeed]

As workaround, are you able to add validation at the field level (e.g. +kubebuilder:validation:MinProperties) that would then make the linter understand that you aren't expecting a zero value here?

[JoelSpeed]

/help

[kubernetes-prow]

@JoelSpeed:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

Details

In response to this:

/help

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.

[rishh09]

Hi, I’d like to work on this.

My current understanding is that requiredfields and optionalfields are treating non-pointer struct fields with json:",omitzero" similarly to fields that cannot be omitted, so they still report that the field should use a pointer or should have omitempty.

I’m planning to first check whether omitzero can be handled in the same tag parsing path where these analyzers currently check for omitempty, then add regression tests using the examples from this issue:

• metav1.Time
• corev1.LocalObjectReference
• required and optional fields with json:",omitzero"

If that does not fully address the false positives, I’ll look at whether a narrow well-known Kubernetes type exception is needed.

We may connect on Discord Rishav#5616

Does that approach sound reasonable?

[JoelSpeed]

The linters already handle omitzero for structs that they can interpret, those within the local package.

#219 was added to add the same support for external types as well, but it appears not to have resolved @muraee's problem. So some further investigation is required to understand why. It's possibly related to having an IsZero() function.

I can't suggest a solution until we understand what the actual issue is

[rishh09]

I took a look locally and I think I found the remaining gap.
It looks like #219 helped with external types, but for some selector-expression structs the later omitempty / pointer checks still run, so the linter reports extra suggestions even when json:",omitzero" is already present.

I have a local patch that keeps the existing IsStructType behavior as-is, and adds a separate omitzero-specific check for external structs and types with IsZero() bool.

I also added regression tests for an external struct and an external struct with IsZero() bool. go test is passing locally.

[Dasmat13]

hey i looked into this and figured out how to intercept these well known types in the external type logic. i have it working locally and it ignores metav1.Time and corev1.LocalObjectReference correctly now. putting up a pr!

[JoelSpeed]

@rishh09 Did you want to create a PR to demonstrate your approach for comparison with what @Dasmat13 has proposed? Sounds like you've taken different approaches

[rishh09]

@JoelSpeed Yes, I had tried a slightly different approach locally. Instead of adding a Kubernetes-type allowlist, it tries to make the omitzero path handle external structs / IsZero() types more generally.

I'll open a PR with that version so it's easier to compare the two approaches.