github.com/googleapis/api-linter@v1.65.2/docs/rules/0148/field-behavior.md (about)

     1  ---
     2  rule:
     3    aip: 148
     4    name: [core, '0148',field-behavior]
     5    summary: Standard resource fields should have the correct field behavior.
     6  permalink: /148/field-behavior
     7  redirect_from:
     8    - /0148/field-behavior
     9  ---
    10  
    11  # Standard resource fields: Field behavior
    12  
    13  This rule enforces that all standard resource fields have the correct
    14  `google.api.field_behavior`, as mandated in [AIP-148][].
    15  
    16  ## Details
    17  
    18  This rule looks at any message with a `google.api.resource` annotation, and
    19  complains if any of the following fields does not have a
    20  `google.api.field_behavior` annotation with a value of `OUTPUT_ONLY`:
    21  
    22  - `create_time`
    23  - `delete_time`
    24  - `uid`
    25  - `update_time`
    26  
    27  ## Examples
    28  
    29  **Incorrect** code for this rule:
    30  
    31  ```proto
    32  // Incorrect.
    33  message Book {
    34    option (google.api.resource) = {
    35      type: "library.googleapis.com/Book"
    36      pattern: "publishers/{publisher}/books/{book}"
    37    };
    38  
    39    string name = 1;
    40  
    41    // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
    42    google.protobuf.Timestamp create_time = 2;
    43  
    44    // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
    45    google.protobuf.Timestamp update_time = 3;
    46  
    47    // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
    48    google.protobuf.Timestamp delete_time = 4;
    49  
    50    // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
    51    string uid = 5;
    52  }
    53  ```
    54  
    55  **Correct** code for this rule:
    56  
    57  ```proto
    58  // Correct.
    59  message Book {
    60    option (google.api.resource) = {
    61      type: "library.googleapis.com/Book"
    62      pattern: "publishers/{publisher}/books/{book}"
    63    };
    64  
    65    string name = 1;
    66  
    67    google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
    68  
    69    google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
    70  
    71    google.protobuf.Timestamp delete_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
    72  
    73    string uid = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
    74  }
    75  ```
    76  
    77  ## Disabling
    78  
    79  If you need to violate this rule, use a leading comment above the field.
    80  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    81  
    82  ```proto
    83  message Book {
    84    option (google.api.resource) = {
    85      type: "library.googleapis.com/Book"
    86      pattern: "publishers/{publisher}/books/{book}"
    87    };
    88  
    89    string name = 1;
    90  
    91    // (-- api-linter: core::0148::field-behavior=disabled
    92    //     aip.dev/not-precedent: We need to do this because reasons. --)
    93    google.protobuf.Timestamp create_time = 2;
    94  
    95    // (-- api-linter: core::0148::field-behavior=disabled
    96    //     aip.dev/not-precedent: We need to do this because reasons. --)
    97    google.protobuf.Timestamp update_time = 3;
    98  
    99    // (-- api-linter: core::0148::field-behavior=disabled
   100    //     aip.dev/not-precedent: We need to do this because reasons. --)
   101    google.protobuf.Timestamp delete_time = 4;
   102  
   103    // (-- api-linter: core::0148::field-behavior=disabled
   104    //     aip.dev/not-precedent: We need to do this because reasons. --)
   105    string uid = 5;
   106  }
   107  ```
   108  
   109  If you need to violate this rule for an entire file, place the comment at the
   110  top of the file.
   111  
   112  [aip-148]: https://aip.dev/148
   113  [aip.dev/not-precedent]: https://aip.dev/not-precedent