Make API field defaulting and validation less error-prone · Issue #25460 · kubernetes/kubernetes (original) (raw)
There are frequent errors in API field specification, such as:
- default vs inferred (e.g.,
fsType: https://github.com/kubernetes/kubernetes/blob/master/pkg/api/v1/types.go#L557); note that implicitly inferred is discouraged - default vs required
- required/optional vs omitempty
- omitempty vs. pointers
- documentation vs actual defaulting and validation code
For examples of multiple errors in one type, see:
#18885 (comment)
One way to make defaulting and validation less error prone would to be allow them to be specified declaratively, on API fields using tags or comments. Protocol buffers allow literal default values to be specified (though, unlike in Kubernetes, they aren't conveyed on the wire; non-literals, such as fields defaulted from other fields, can't be specified this way). Declarative validation, where possible (i.e., simple rules), was previously requested by #8116.
Since omitempty and pointer rules are apparently non-obvious, I think we should require specification of required vs optional and then either verify that the other properties are consistent or autogenerate them.
Auto-fixing field names in documentation is covered by #19319.