Design runtime-flexible APIs

When extending CRI/ABI-style APIs, avoid over-specifying runtime-variant behavior and instead make contracts that are both implementable and unambiguous for clients.

Guidelines:

• Don’t hard-code format/media-type/validation constraints in the wire contract unless the ecosystem will enforce and conformance-test them. Prefer:
  • “Accepted formats determined by runtime” in the proto/API
  • Recommended formats/structure in KEP/docs.
• Define semantics for fields that change client behavior or observability (events/SLIs). For example, a “cached/present” boolean must precisely state what it means on success vs error.
  • If you use cached, explicitly document whether it applies to “no registry request made” and whether it is returned only on success.
• Model runtime capability support with explicit, granular capability fields (e.g., specific mount modes), not generic/version-dependent guesses.
  • This prevents kubelet/clients from assuming support for newly added options.
• For numeric/config fields:
  • Specify validation expectations (e.g., no duplicate keys; min/max bounds).
  • Choose primitive types and bounds to survive JSON/YAML round-tripping (avoid values beyond JS safe integer when using int-like fields).
  • Enforce constraints at the API layer where possible so invalid configs fail early, not after container/runtime attempts.

Example (semantic precision for cached):

// cached is true only when the profile is already present for this request and
// no registry/verification was performed. cached=false means the runtime
// actually checked/served/validated for this request (or the call failed).
// The field is only returned on successful calls.
bool cached = 1;