docs: add docs around when to use declarative vs hand-Written validation and when to create a new declarative validation tag #8623
Conversation
k8s-ci-robot
added
cncf-cla: yes
k8s-ci-robot
added
sig/contributor-experience
…ion and when to create a new declarative validation tag
aaron-prindle
force-pushed
the
when-to-dv-docs
branch
from
493595a to
69c9e2b
Compare
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: aaron-prindle, soltysh The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
| #### When to Use Declarative Validation vs Hand-Written Validation | ||
|
|
||
| **Use Declarative Validation when:** | ||
| - The validation rule has an existing stable declarative validation tag which can be used in a straightforward way. See the catalog of stable tags [here](https://kubernetes.io/docs/reference/using-api/declarative-validation/). |
There was a problem hiding this comment.
looking at https://kubernetes.io/docs/reference/using-api/declarative-validation/#catalog, am I missing how to tell for each tag what its stability level is?
| **Use Declarative Validation when:** | ||
| - The validation rule has an existing stable declarative validation tag which can be used in a straightforward way. See the catalog of stable tags [here](https://kubernetes.io/docs/reference/using-api/declarative-validation/). | ||
| - You are working on a new API or adding new fields to an existing API that already uses declarative validation. | ||
| - The validation rule is simple and linear (e.g., min/max values, string length, format checks). |
| - You are working on a new API or adding new fields to an existing API that already uses declarative validation. | ||
| - The validation rule is simple and linear (e.g., min/max values, string length, format checks). | ||
| - The validation can be expressed as a property of the data schema. | ||
| - The validation pattern is reusable across multiple APIs. |
There was a problem hiding this comment.
What does this bit mean in the context of a single field in a single API? this seems more related to deciding whether or not to add a new tag (the section below).
The "The validation rule has an existing stable declarative validation tag" item above makes it seem like DV would only be considered for things already deemed common enough to have tags added
| - The validation requires complex logic or conditional branching based on multiple fields. | ||
| - The validation needs to consider external state beyond the object itself. | ||
| - Custom, detailed error messages are required for different failure conditions. | ||
| - The validation logic is unique to a specific API and unlikely to be reused. |
There was a problem hiding this comment.
same question here... isn't this bit about whether or not to add a new tag?
| 4) Any tag we add should be something we are OK with people using in new APIs. (We may eventually add tags that capture legacy semantics which break this rule). | ||
| 5) With rare and clear exceptions, tags should not be interdependent. | ||
| 6) Tags should usually represent properties of the data (schema) and the API operation (e.g. update), rather than the act of validation. | ||
| 7) Tags are written from the POV of an API client. |
There was a problem hiding this comment.
| 7) Tags are written from the POV of an API client. | |
| 7) Tags are written from the point of view of an API client. |
| 5) With rare and clear exceptions, tags should not be interdependent. | ||
| 6) Tags should usually represent properties of the data (schema) and the API operation (e.g. update), rather than the act of validation. | ||
| 7) Tags are written from the POV of an API client. | ||
| 8) Tags should be as orthogonal as possible. |
There was a problem hiding this comment.
nit: could probably combine this with the tags should not be interdependent item
|
|
||
| #### When to Use Declarative Validation vs Hand-Written Validation | ||
|
|
||
| **Use Declarative Validation when:** |
There was a problem hiding this comment.
is this an "all of these must be true" list or "any of these may be true"?
| 6) Tags should usually represent properties of the data (schema) and the API operation (e.g. update), rather than the act of validation. | ||
| 7) Tags are written from the POV of an API client. | ||
| 8) Tags should be as orthogonal as possible. | ||
| 9) Tags should be linear and (with rare exceptions) not represent complex logic. |
There was a problem hiding this comment.
same question about what linear means
|
|
||
| 1) Any tag added should be as simple and intuitive as possible to read. | ||
| 2) Any tag added should plausibly be applicable to many APIs. | ||
| 3) Any tag added should represent our current understanding of the best way to express an idea. |
There was a problem hiding this comment.
I'm not sure I understand what this is getting at ... is this saying we won't create new tags to capture validation patterns we no longer consider a good idea? Is that the same as "Any tag we add should be something we are OK with people using in new APIs"?
| 7) Tags are written from the POV of an API client. | ||
| 8) Tags should be as orthogonal as possible. | ||
| 9) Tags should be linear and (with rare exceptions) not represent complex logic. | ||
| 10) Tags should not need to consider anything other than the object(s) in question and configured options (e.g. feature gates). |
There was a problem hiding this comment.
possible suggestion: using the same language above about "external state" might be clearer
Tags should not need to consider external state beyond the new object being validated, the existing object (for update operations), the operation / resource / subresource, and configured options (e.g. feature gates).
PR adds documentation around when to use declarative vs hand-Written validation and when to create a new declarative validation tag.
Related to KEP 5073: