diff options
| author | Eric Tune <etune@google.com> | 2016-01-15 14:34:46 -0800 |
|---|---|---|
| committer | Eric Tune <etune@google.com> | 2016-02-03 13:25:18 -0800 |
| commit | dfa00a5742b5eab0df2e98fcc70539cb97e1f876 (patch) | |
| tree | 0908651831420ba89ae3f85f1a3c580a6b258896 /api-conventions.md | |
| parent | 7cba47d83d4941948d4c55557f150a25635ca4f4 (diff) | |
Document Unions, conventions for adding to Unions.
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": |