enum-zero-value-suffix (Protobuf linter rule)

enum-zero-value-suffix

Since 0.9.0

This rule checks whether the zero value of every enum ends with a suffix, _UNSPECIFIED by default.

Rule Details

In proto3, the zero value is the default of every enum field: a field that was never set reads as zero. A name like PET_KIND_UNSPECIFIED makes it clear that the zero value means “not set”, rather than a real value such as PET_KIND_DOG that clients would then receive by accident.

The enum-zero-value-suffix rule checks every enum value whose number is 0, and reports Enum zero value '<value>' should end with '<suffix>' when its name does not end with the suffix. When an enum allows aliases, every value numbered 0 is checked.

Configuration

The configuration block can be a string or an object.

If it is a string, its value is the suffix.

If it is an object, it must contain only the suffix property, whose value is the suffix.

The suffix cannot be empty.

Configuration Example. The following two examples are equivalent. They specify that the zero values must end with _UNKNOWN.

version: "1.0"
commands:
  lint:
    protobuf:
      rules:
        enum-zero-value-suffix: [warning, _UNKNOWN]

version: "1.0"
commands:
  lint:
    protobuf:
      rules:
        enum-zero-value-suffix:
          - warning
          - suffix: _UNKNOWN

Examples

Good. With the default configuration.

syntax = "proto3";

package acme.pets.v1;

enum PetKind {
  PET_KIND_UNSPECIFIED = 0;
  PET_KIND_DOG = 1;
}

Bad. With the default configuration, the linter reports Enum zero value 'PET_KIND_UNKNOWN' should end with '_UNSPECIFIED'.

syntax = "proto3";

package acme.pets.v1;

enum PetKind {
  PET_KIND_UNKNOWN = 0;
  PET_KIND_DOG = 1;
}

When Not to Use It

You may disable this rule if the zero value of some enums is a meaningful value, for example in enums mirroring an external standard. To allow a single enum, add an // apigenie-lint-disable enum-zero-value-suffix comment to the enum.

Compatibility