AEP-0148 Linter Rules

Declarative-friendly fields

This rule requires certain standard fields on declarative-friendly resources, as mandated in [AIP-148][].

Details

This rule looks at any resource with a google.api.resource annotation that includes style: DECLARATIVE_FRIENDLY, and complains if it does not include all of the following fields:

string path
string uid
string display_name
google.protobuf.Timestamp create_time
google.protobuf.Timestamp update_time
google.protobuf.Timestamp delete_time

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}
    style: DECLARATIVE_FRIENDLY
  };

  string path = 1;
  // string uid should be included!
  string display_name = 2;
  google.protobuf.Timestamp create_time = 3;
  google.protobuf.Timestamp update_time = 4;
  // google.protobuf.Timestamp delete_time should be included!
}

Correct code for this rule:

// Correct.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}
    style: DECLARATIVE_FRIENDLY
  };

  string path = 1;
  string uid = 2;
  string display_name = 3;
  google.protobuf.Timestamp create_time = 4;
  google.protobuf.Timestamp update_time = 5;
  google.protobuf.TImestamp delete_time = 6;
}

Disabling

If you need to violate this rule, use a leading comment above the message. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0148::declarative-friendly-fields=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}
    style: DECLARATIVE_FRIENDLY
  };

  string path = 1;
  // string uid should be included!
  string display_name = 2;
  google.protobuf.Timestamp create_time = 3;
  google.protobuf.Timestamp update_time = 4;
  // google.protobuf.Timestamp delete_time should be included!
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Standard resource fields- Field behavior

Standard resource fields: Field behavior

This rule enforces that all standard resource fields have the correct google.api.field_behavior, as mandated in [AIP-148][].

Details

This rule looks at any message with a google.api.resource annotation, and complains if any of the following fields does not have a google.api.field_behavior annotation with a value of OUTPUT_ONLY:

create_time
delete_time
uid
update_time

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  string path = 1;

  // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
  google.protobuf.Timestamp create_time = 2;

  // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
  google.protobuf.Timestamp update_time = 3;

  // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
  google.protobuf.Timestamp delete_time = 4;

  // The `google.api.field_behavior` annotation should be `OUTPUT_ONLY`.
  string uid = 5;
}

Correct code for this rule:

// Correct.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  string path = 1;

  google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  google.protobuf.Timestamp delete_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  string uid = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
}

Disabling

If you need to violate this rule, use a leading comment above the field. Remember to also include an aep.dev/not-precedent comment explaining why.

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  string path = 1;

  // (-- api-linter: core::0148::field-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  google.protobuf.Timestamp create_time = 2;

  // (-- api-linter: core::0148::field-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  google.protobuf.Timestamp update_time = 3;

  // (-- api-linter: core::0148::field-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  google.protobuf.Timestamp delete_time = 4;

  // (-- api-linter: core::0148::field-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string uid = 5;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Human names

This rule encourages terms for human names (given_name and family_name) that are more accurate across cultures, as mandated in [AIP-148][].

Details

This rule looks for fields named first_name and last_name, and complains if it finds them, suggesting the use of given_name and family_name (respectively) instead.

Examples

Incorrect code for this rule:

// Incorrect.
message Human {
  string first_name = 1;  // Should be `given_name`.
  string last_name = 2;   // Should be `family_name`
}

Correct code for this rule:

// Correct.
message Human {
  string given_name = 1;
  string family_name = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the field or its enclosing message. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0148::human-names=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Human {
  string first_name = 1;
  string last_name = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

IP Address field format annotation

This rule encourages the use of one of the IP Address format annotations, IPV4, IPV6, or IPV4_OR_IPV6, on the ip_address field or a field ending with _ip_address, as mandated in [AIP-148][].

Details

This rule looks on for fields named ip_address or ending with _ip_address and complains if it does not have the (google.api.field_info).format annotation with one of IPV4, IPV6, or IPV4_OR_IPV6, or has a format other than than one of those.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
  string ip_address = 2; // missing (google.api.field_info).format = IPV4
}

Correct code for this rule:

// Correct.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
  string ip_address = 2 [(google.api.field_info).format = IPV4];
}

Disabling

If you need to violate this rule, use a leading comment above the field or its enclosing message. Remember to also include an aep.dev/not-precedent comment explaining why.

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string path = 1 [(google.api.field_behavior) = IDENTIFIER];

  // (-- api-linter: core::0148::ip-address-format=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string ip_address = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

uid format annotation

`uid` format annotation

This rule encourages the use of the UUID4 format annotation on the uid field, as mandated in [AIP-148][].

Details

This rule looks on for fields named uid and complains if it does not have the (google.api.field_info).format = UUID4 annotation or has a format other than UUID4.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
  string uid = 2; // missing (google.api.field_info).format = UUID4
}

Correct code for this rule:

// Correct.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
  string uid = 2 [(google.api.field_info).format = UUID4];
}

Disabling

If you need to violate this rule, use a leading comment above the field or its enclosing message. Remember to also include an aep.dev/not-precedent comment explaining why.

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string path = 1 [(google.api.field_behavior) = IDENTIFIER];

  // (-- api-linter: core::0148::uid-format=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string uid = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.