From e1ded93ff37ab654682ff38c0e77e47c6a7681e6 Mon Sep 17 00:00:00 2001 From: "Tim St. Clair" Date: Mon, 23 Nov 2015 18:06:23 -0800 Subject: [PATCH] Clarify when pointers are used for optional types --- api-conventions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api-conventions.md b/api-conventions.md index 6628e9983..43550903a 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