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

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