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

     1  ---
     2  rule:
     3    aip: 122
     4    name: [core, '0122', embedded-resource]
     5    summary: Resource references should not be embedded resources.
     6  permalink: /122/embedded-resource
     7  redirect_from:
     8    - /0122/embedded-resource
     9  ---
    10  
    11  # Resource reference type
    12  
    13  This rule enforces that references to resource are via
    14  `google.api.resource_reference`, not by embedding the resource message, as
    15  mandated in [AIP-122][].
    16  
    17  ## Details
    18  
    19  This rule complains if it sees a resource field of type `message` that is also
    20  annotated as a `google.api.resource`.
    21  
    22  ## Examples
    23  
    24  **Incorrect** code for this rule:
    25  
    26  ```proto
    27  // Incorrect.
    28  message Book {
    29    option (google.api.resource) = {
    30      type: "library.googleapis.com/Book"
    31      pattern: "books/{book}"
    32    };
    33    string name = 1;
    34  
    35    // Incorrect. Resource references should not be embedded resource messages.
    36    Author author = 2;
    37  }
    38  
    39  message Author {
    40      option (google.api.resource) = {
    41          type: "library.googleapis.com/Author"
    42          pattern: "authors/{author}"
    43      };
    44  
    45      string name = 1;
    46  }
    47  ```
    48  
    49  **Correct** code for this rule:
    50  
    51  ```proto
    52  // Correct.
    53  message Book {
    54    option (google.api.resource) = {
    55      type: "library.googleapis.com/Book"
    56      pattern: "books/{book}"
    57    };
    58    string name = 1;
    59  
    60    string author = 2 [(google.api.resource_reference) = {
    61      type: "library.googleapis.com/Author"
    62    }];
    63  }
    64  
    65  message Author {
    66      option (google.api.resource) = {
    67          type: "library.googleapis.com/Author"
    68          pattern: "authors/{author}"
    69      };
    70  
    71      string name = 1;
    72  }
    73  ```
    74  
    75  ## Disabling
    76  
    77  If you need to violate this rule, use a leading comment above the method.
    78  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    79  
    80  ```proto
    81  message Book {
    82    option (google.api.resource) = {
    83      type: "library.googleapis.com/Book"
    84      pattern: "books/{book}"
    85    };
    86    string name = 1;
    87  
    88    // (-- api-linter: core::0122::embedded-resource=disabled
    89    //     aip.dev/not-precedent: We need to do this because reasons. --)
    90    Author author = 2;
    91  }
    92  
    93  message Author {
    94      option (google.api.resource) = {
    95          type: "library.googleapis.com/Author"
    96          pattern: "authors/{author}"
    97      };
    98  
    99      string name = 1;
   100  }
   101  ```
   102  
   103  If you need to violate this rule for an entire file, place the comment at the
   104  top of the file.
   105  
   106  [aip-122]: https://aip.dev/122
   107  [aip.dev/not-precedent]: https://aip.dev/not-precedent