Skip to content

Commit b650843

Browse files
committed
Address review feedback
1 parent 62e4abc commit b650843

File tree

1 file changed

+10
-2
lines changed

1 file changed

+10
-2
lines changed

contributors/devel/sig-architecture/api-conventions.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -871,13 +871,21 @@ have a built-in `nil` value.
871871

872872
The `+nullable` comment tag allows the json `null` value to be a valid value
873873
for a field. The `null` value is serialized only when a field is a pointer
874-
in the Go definition, and does not have the `omitempty` json tag.
874+
in the Go definition, and does not have the `omitempty` json tag, or sometimes where a
875+
custom marshal function is implemented.
875876

876877
For example, a map field marked with `+nullable` would accept either `foo: null` or `foo: {}`.
877878

878879
Usage of `+nullable` is discouraged as it introduces several issues:
879880
- It is not compatible with json merge patching.
880-
- It is not compatible with generic protobuf.
881+
- From the [JSON Merge Patch RFC](https://tools.ietf.org/html/rfc7386#section-1):
882+
> Null values in the merge patch are given special meaning to indicate the removal of existing values in the target.
883+
- Explicit `null` values are not be persisted in proto serializations.
884+
- `null` values are not supported by Server-Side Apply applyconfiguration types.
885+
- A persisted `null` value would not round-trip through the applyconfiguration type
886+
encode/decode cycle.
887+
888+
Avoid designing APIs that require the distinction bewteen unset and `null`.
881889

882890
## Defaulting
883891

0 commit comments

Comments
 (0)