github.com/googleapis/api-linter@v1.65.2/docs/rules/0163/declarative-friendly-required.md (about)

     1  ---
     2  rule:
     3    aip: 163
     4    name: [core, '0163', declarative-friendly-required]
     5    summary: Declarative-friendly mutations should have a validate_only field.
     6  permalink: /163/declarative-friendly-required
     7  redirect_from:
     8    - /0163/declarative-friendly-required
     9  ---
    10  
    11  # Required change validation
    12  
    13  This rule enforces that declarative-friendly mutations have a `validate_only`
    14  field, as mandated in [AIP-163][].
    15  
    16  ## Details
    17  
    18  This rule looks at any mutation (`POST`, `PATCH`, `DELETE`) connected to a
    19  resource with a `google.api.resource` annotation that includes
    20  `style: DECLARATIVE_FRIENDLY`, and complains if it lacks a `bool validate_only`
    21  field.
    22  
    23  ## Examples
    24  
    25  **Incorrect** code for this rule:
    26  
    27  ```proto
    28  // Incorrect.
    29  // Assuming that Book is styled declarative-friendly...
    30  message DeleteBookRequest {
    31    string name = 1 [(google.api.resource_reference) = {
    32      type: "library.googleapis.com/Book"
    33    }];
    34    // A bool validate_only field should exist.
    35  }
    36  ```
    37  
    38  **Correct** code for this rule:
    39  
    40  ```proto
    41  // Correct.
    42  // Assuming that Book is styled declarative-friendly...
    43  message DeleteBookRequest {
    44    string name = 1 [(google.api.resource_reference) = {
    45      type: "library.googleapis.com/Book"
    46    }];
    47    bool validate_only = 2;
    48  }
    49  ```
    50  
    51  ## Disabling
    52  
    53  If you need to violate this rule, use a leading comment above the message.
    54  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    55  
    56  ```proto
    57  // (-- api-linter: core::0163::declarative-friendly-required=disabled
    58  //     aip.dev/not-precedent: We need to do this because reasons. --)
    59  message DeleteBookRequest {
    60    string name = 1 [(google.api.resource_reference) = {
    61      type: "library.googleapis.com/Book"
    62    }];
    63  }
    64  ```
    65  
    66  **Note:** Violations of declarative-friendly rules should be rare, as tools are
    67  likely to expect strong consistency.
    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-163]: https://aip.dev/163
    73  [aip.dev/not-precedent]: https://aip.dev/not-precedent