github.com/googleapis/api-linter@v1.65.2/docs/rules/0148/ip-address-format.md (about)

     1  ---
     2  rule:
     3    aip: 148
     4    name: [core, '0148', ip-address-format]
     5    summary: Annotate IP address fields with an IP address format.
     6  permalink: /148/ip-address-format
     7  redirect_from:
     8    - /0148/ip-address-format
     9  ---
    10  
    11  # IP Address field format annotation
    12  
    13  This rule encourages the use of one of the IP Address format annotations,
    14  `IPV4`, `IPV6`, or `IPV4_OR_IPV6`, on the `ip_address` field or a field ending
    15  with `_ip_address`, as mandated in [AIP-148][].
    16  
    17  ## Details
    18  
    19  This rule looks on for fields named `ip_address` or ending with `_ip_address`
    20  and complains if it does not have the `(google.api.field_info).format`
    21  annotation with one of `IPV4`, `IPV6`, or `IPV4_OR_IPV6`, or has a format other
    22  than than one of those.
    23  
    24  ## Examples
    25  
    26  **Incorrect** code for this rule:
    27  
    28  ```proto
    29  // Incorrect.
    30  message Book {
    31    option (google.api.resource) = {
    32      type: "library.googleapis.com/Book"
    33      pattern: "books/{book}"
    34    };
    35  
    36    string name = 1 [(google.api.field_behavior) = IDENTIFIER];
    37    string ip_address = 2; // missing (google.api.field_info).format = IPV4
    38  }
    39  ```
    40  
    41  **Correct** code for this rule:
    42  
    43  ```proto
    44  // Correct.
    45  message Book {
    46    option (google.api.resource) = {
    47      type: "library.googleapis.com/Book"
    48      pattern: "books/{book}"
    49    };
    50  
    51    string name = 1 [(google.api.field_behavior) = IDENTIFIER];
    52    string ip_address = 2 [(google.api.field_info).format = IPV4];
    53  }
    54  ```
    55  
    56  ## Disabling
    57  
    58  If you need to violate this rule, use a leading comment above the field or its
    59  enclosing message. Remember to also include an [aip.dev/not-precedent][]
    60  comment explaining why.
    61  
    62  ```proto
    63  message Book {
    64    option (google.api.resource) = {
    65      type: "library.googleapis.com/Book"
    66      pattern: "books/{book}"
    67    };
    68  
    69    string name = 1 [(google.api.field_behavior) = IDENTIFIER];
    70  
    71    // (-- api-linter: core::0148::ip-address-format=disabled
    72    //     aip.dev/not-precedent: We need to do this because reasons. --)
    73    string ip_address = 2;
    74  }
    75  ```
    76  
    77  If you need to violate this rule for an entire file, place the comment at the
    78  top of the file.
    79  
    80  [aip-148]: https://aip.dev/148
    81  [aip.dev/not-precedent]: https://aip.dev/not-precedent