github.com/googleapis/api-linter@v1.65.2/docs/rules/0214/resource-expiry.md (about)

     1  ---
     2  rule:
     3    aip: 214
     4    name: [core, '0214', resource-expiry]
     5    summary: Resources with user-set expiry times should offer a ttl field.
     6  permalink: /214/resource-expiry
     7  redirect_from:
     8    - /0214/resource-expiry
     9  ---
    10  
    11  # Resource expiry
    12  
    13  This rule enforces that resources that have an expire time that can be set by
    14  users also have an input-only `ttl` field, as recommended in [AIP-214][].
    15  
    16  ## Details
    17  
    18  This rule looks at fields named `expire_time`, and complains if **none** of the
    19  following conditions are met:
    20  
    21  - A field named `ttl` also exists in the message.
    22  - The `expire_time` field is annotated as `OUTPUT_ONLY`.
    23  
    24  ## Examples
    25  
    26  **Incorrect** code for this rule:
    27  
    28  ```proto
    29  // Incorrect.
    30  message Book {
    31    string name = 1;
    32    google.protobuf.Timestamp expire_time = 2;  // Should have `ttl` also.
    33  }
    34  ```
    35  
    36  **Correct** code for this rule:
    37  
    38  ```proto
    39  // Correct.
    40  message Book {
    41    string name = 1;
    42    google.protobuf.Timestamp expire_time = 2
    43      [(google.api.field_behavior) = OUTPUT_ONLY];
    44  }
    45  ```
    46  
    47  ```proto
    48  // Correct.
    49  message Book {
    50    string name = 1;
    51    oneof expiration {
    52      google.protobuf.Timestamp expire_time = 2;
    53      google.protobuf.Duration ttl = 3;
    54    }
    55  }
    56  ```
    57  
    58  ## Disabling
    59  
    60  If you need to violate this rule, use a leading comment above the enum.
    61  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    62  
    63  ```proto
    64  message Book {
    65    string name = 1;
    66    // (-- api-linter: core::0214::resource-expiry=disabled
    67    //     aip.dev/not-precedent: We need to do this because reasons. --)
    68    google.protobuf.Timestamp expire_time = 2
    69      [(google.api.field_behavior) = OUTPUT_ONLY];
    70  }
    71  ```
    72  
    73  If you need to violate this rule for an entire file, place the comment at the
    74  top of the file.
    75  
    76  [aip-214]: https://aip.dev/214
    77  [aip.dev/not-precedent]: https://aip.dev/not-precedent