diff options
| author | Tim St. Clair <stclair@google.com> | 2015-11-23 18:06:23 -0800 |
|---|---|---|
| committer | Tim St. Clair <stclair@google.com> | 2015-11-23 18:06:23 -0800 |
| commit | e1ded93ff37ab654682ff38c0e77e47c6a7681e6 (patch) | |
| tree | 3833cf0770afa05c01d77e0d9ac809b9a32cb6e5 | |
| parent | ccd0d84dc966dfe49553fcc88efd5c4c7c0fbac6 (diff) | |
Clarify when pointers are used for optional types
| -rw-r--r-- | api-conventions.md | 6 |
1 files changed, 4 insertions, 2 deletions
diff --git a/api-conventions.md b/api-conventions.md index 6628e998..43550903 100644 --- a/api-conventions.md +++ b/api-conventions.md @@ -387,7 +387,8 @@ Fields must be either optional or required. Optional fields have the following properties: - They have `omitempty` struct tag in Go. -- They are a pointer type in the Go definition (e.g. `bool *awesomeFlag`). +- They are a pointer type in the Go definition (e.g. `bool *awesomeFlag`) or have a built-in `nil` + value (e.g. maps and slices). - The API server should allow POSTing and PUTing a resource with this field unset. Required fields have the opposite properties, namely: @@ -409,7 +410,8 @@ codebase. However: - having a pointer consistently imply optional is clearer for users of the Go language client, and any other clients that use corresponding types -Therefore, we ask that pointers always be used with optional fields. +Therefore, we ask that pointers always be used with optional fields that do not have a built-in +`nil` value. ## Defaulting |