enum-zero-value-suffix

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

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.

Turn the rule off 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.

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;
}

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.protobuf has the details.

commands:
  lint:
    protobuf:
      rules:
        enum-zero-value-suffix: off

Related rules

Was this helpful?