github.com/googleapis/api-linter@v1.65.2/docs/rules/0126/unspecified.md (about)

     1  ---
     2  rule:
     3    aip: 126
     4    name: [core, '0126', unspecified]
     5    summary: All enums must have a default unspecified value.
     6  permalink: /126/unspecified
     7  redirect_from:
     8    - /0126/unspecified
     9  ---
    10  
    11  # Enum unspecified value
    12  
    13  This rule enforces that all enums have a default unspecified value, as mandated
    14  in [AIP-126][].
    15  
    16  Because our APIs create automatically-generated client libraries, we need to
    17  consider languages that have varying behavior around default values. To avoid
    18  any ambiguity or confusion across languages, all enumerations should use an
    19  "unspecified" value beginning with the name of the enum itself as the first
    20  (`0`) value.
    21  
    22  ## Details
    23  
    24  This rule finds all enumerations and ensures that the first one is named after
    25  the enum itself with an `_UNSPECIFIED` suffix appended.
    26  
    27  ## Examples
    28  
    29  **Incorrect** code for this rule:
    30  
    31  ```proto
    32  // Incorrect.
    33  enum Format {
    34    HARDCOVER = 0;  // Should have "FORMAT_UNSPECIFIED" first.
    35  }
    36  ```
    37  
    38  ```proto
    39  // Incorrect.
    40  enum Format {
    41    UNSPECIFIED = 0;  // Should be "FORMAT_UNSPECIFIED".
    42    HARDCOVER = 1;
    43  }
    44  ```
    45  
    46  **Correct** code for this rule:
    47  
    48  ```proto
    49  // Correct.
    50  enum Format {
    51    FORMAT_UNSPECIFIED = 0;
    52    HARDCOVER = 1;
    53  }
    54  ```
    55  
    56  ## Disabling
    57  
    58  If you need to violate this rule, use a leading comment above the enum value.
    59  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    60  
    61  ```proto
    62  enum Format {
    63    // (-- api-linter: core::0126::unspecified=disabled
    64    //     aip.dev/not-precedent: We need to do this because reasons. --)
    65    HARDCOVER = 0;
    66  }
    67  ```
    68  
    69  If you need to violate this rule for an entire file, place the comment at the
    70  top of the file.
    71  
    72  [aip-126]: https://aip.dev/126
    73  [aip.dev/not-precedent]: https://aip.dev/not-precedent