diff options
| author | k8s-merge-robot <k8s.production.user@gmail.com> | 2016-02-07 22:16:13 -0800 |
|---|---|---|
| committer | k8s-merge-robot <k8s.production.user@gmail.com> | 2016-02-07 22:16:13 -0800 |
| commit | 44d43e314ce99cada01aea5133d82b3424cd5223 (patch) | |
| tree | 9cee64cddf87f3d7e3d20bc6b2011b9dc73aa617 /api-conventions.md | |
| parent | a6431996de8ccabafc3eb47ebbe4460e98f1fe98 (diff) | |
| parent | dfa00a5742b5eab0df2e98fcc70539cb97e1f876 (diff) | |
Merge pull request #20585 from erictune/api-unions
Auto commit by PR queue bot
Diffstat (limited to 'api-conventions.md')
| -rw-r--r-- | api-conventions.md | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/api-conventions.md b/api-conventions.md index c5fda4bb..af02d3db 100644 --- a/api-conventions.md +++ b/api-conventions.md @@ -53,6 +53,7 @@ using resources with kubectl can be found in [Working with resources](../user-gu - [Lists of named subobjects preferred over maps](#lists-of-named-subobjects-preferred-over-maps) - [Primitive types](#primitive-types) - [Constants](#constants) + - [Unions](#unions) - [Lists and Simple kinds](#lists-and-simple-kinds) - [Differing Representations](#differing-representations) - [Verbs on Resources](#verbs-on-resources) @@ -263,6 +264,15 @@ This rule maintains the invariant that all JSON/YAML keys are fields in API obje Some fields will have a list of allowed values (enumerations). These values will be strings, and they will be in CamelCase, with an initial uppercase letter. Examples: "ClusterFirst", "Pending", "ClientIP". +#### Unions + +Sometimes, at most one of a set of fields can be set. For example, the [volumes] field of a PodSpec has 17 different volume type-specific +fields, such as `nfs` and `iscsi`. All fields in the set should be [Optional](#optional-vs-required). + +Sometimes, when a new type is created, the api designer may anticipate that a union will be needed in the future, even if only one field is +allowed initially. In this case, be sure to make the field [Optional](#optional-vs-required) optional. In the validation, you may +still return an error if the sole field is unset. Do not set a default value for that field. + ### Lists and Simple kinds Every list or simple kind SHOULD have the following metadata in a nested object field called "metadata": |