Core rules

Core rules are based on generally-applicable AIPs. They are enabled by default, and should be enabled for most APIs. It is recommended that APIs which do not want to follow certain AIPs within the core section disable those rules individually, rather than disabling the core rules as a set.

Expand all Collapse all

AIP-122

camel-case-uris All resource names must use camel case in collection identifiers.
name-suffix Fields should not use the suffix `_name`.
resource-reference-type All resource references must be strings.

AIP-123

resource-annotation Resource messages should be annotated with `google.api.resource`.
resource-pattern Resource annotations should define a pattern.
resource-variables Resource patterns should use consistent variable naming.

AIP-124

reference-same-package Resource references should refer to resources in the same package.
valid-reference Resource references should have corresponding resource defintions.

AIP-126

unspecified All enums must have a default unspecified value.
upper-snake-values All enum values must be in upper snake case.

AIP-127

http-annotation HTTP annotations must be present on non-streaming methods.
resource-name-extraction HTTP annotations should extract full resource names into variables.

AIP-128

resource-annotations-field Declarative-friendly resources must have an `annotations` field.
resource-reconciling-field Declarative-friendly resources must have a `reconciling` field.

AIP-131

http-body Get methods must not have an HTTP body.
http-method Get methods must use the GET HTTP verb.
http-uri-name Get methods must map the name field to the URI.
method-signature Get RPCs should annotate a method signature of "name".
request-message-name Get methods must have standardized request message names.
request-name-behavior Get RPCs should annotate the `name` field with `google.api.field_behavior`.
request-name-field Get RPCs must have a `string name` field in the request.
request-name-reference Get RPCs should annotate the `name` field with `google.api.resource_reference`.
request-name-required Get RPCs must have a `name` field in the request.
request-unknown-fields Get RPCs should not have unexpected fields in the request.
response-message-name Get methods must return the resource.
synonyms Get methods must be named starting with "Get".

AIP-132

http-body List methods must not have an HTTP body.
http-method List methods must use the GET HTTP verb.
method-signature List RPCs should annotate a method signature of "parent".
request-field-types List RPCs should have fields with consistent types.
request-message-name List methods must have standardized request message names.
request-parent-behavior List RPCs should annotate the `parent` field with `google.api.field_behavior`.
request-parent-field List RPCs must have a `parent` field in the request.
request-parent-reference List RPCs should annotate the `parent` field with `google.api.resource_reference`.
request-parent-required List RPCs must have a `parent` field in the request.
request-unknown-fields List RPCs should not have unexpected fields in the request.
response-message-name List methods must have standardized response message names.
response-unknown-fields List RPCs should not have unexpected fields in the response.

AIP-133

http-body Create methods must have the HTTP body set to the resource.
http-method Create methods must use the POST HTTP verb.
http-uri-parent Create methods must map the parent field to the URI.
method-signature Create RPCs should annotate an appropriate method signature.
request-id-field Declarative-friendly create methods should have a client-specified ID field.
request-message-name Create methods must have standardized request message names.
request-parent-behavior Create RPCs should annotate the `parent` field with `google.api.field_behavior`.
request-parent-field Create RPCs must have a `parent` field in the request.
request-parent-reference Create RPCs should annotate the `parent` field with `google.api.resource_reference`.
request-parent-required Create RPCs must have a `parent` field in the request.
request-resource-behavior Create RPCs should annotate the resource field with `google.api.field_behavior`.
request-resource-field Create RPCs must have a field for the resource in the request.
request-unknown-fields Create RPCs should not have unexpected fields in the request.
response-lro Declarative-friendly create methods should use long-running operations.
response-message-name Create methods must return the resource.
synonyms Create methods must be named starting with "Create".

AIP-134

http-body Update methods must have the HTTP body set to the resource.
http-method Update methods must use the PATCH HTTP verb.
http-uri-name Update methods must map the resource's name field to the URI.
method-signature Update RPCs should annotate an appropriate method signature.
request-allow-missing-field Update RPCs on declarative-friendly resources should include allow_missing.
request-mask-field Update RPCs must have a field mask in the request.
request-mask-required Update RPCs must have a field mask in the request.
request-message-name Update methods must have standardized request message names.
request-resource-field Update RPCs must have a field for the resource in the request.
request-resource-required Update RPCs must have a field for the resource in the request.
request-unknown-fields Update RPCs should not have unexpected fields in the request.
response-lro Declarative-friendly Update methods should use long-running operations.
response-message-name Update methods must return the resource.
synonyms Update methods must be named starting with "Update".

AIP-135

http-body Delete methods must not have an HTTP body.
http-method Delete methods must use the DELETE HTTP verb.
http-uri-name Delete methods must map the name field to the URI.
method-signature Delete RPCs should annotate a method signature of "name".
request-message-name Delete methods must have standardized request message names.
request-name-behavior Delete RPCs should annotate the `name` field with `google.api.field_behavior`.
request-name-field Delete RPCs must have a `name` field in the request.
request-name-reference Delete RPCs should annotate the `name` field with `google.api.resource_reference`.
request-name-required Delete RPCs must have a `name` field in the request.
request-unknown-fields Delete RPCs should not have unexpected fields in the request.
response-lro Declarative-friendly delete methods should use long-running operations.
response-message-name Delete methods must return Empty or the resource.

AIP-136

http-body Custom methods must have the HTTP body set to `*`.
http-method Custom methods must use the POST or GET HTTP verb.
http-name-variable Custom methods should only use `name` if the RPC noun matches the resource.
http-parent-variable Custom methods should only use `parent` if the RPC noun matches the resource.
http-uri-suffix Custom methods should have a correct URI suffix.
prepositions Custom methods must not include prepositions in their names.
standard-methods-only Declarative-friendly resources should eschew custom methods.
verb-noun Custom methods should be named with the verb, then the noun.

AIP-140

abbreviations Field names should use common abbreviations.
base64 Base64 fields should use the `bytes` type.
lower-snake Field names should use `snake_case`.
numbers Field names should not have words beginning with numbers.
prepositions Fields must not include prepositions in their names.
reserved-words Field names must not be reserved words.
uri Field names should prefer `uri` to `url`.

AIP-141

count-suffix Quantities should use a `_count` suffix.
forbidden-types Fields should avoid unsigned integer types.

AIP-142

time-field-names Timestamps should use `google.protobuf.Timestamp`.
time-field-type Timestamps should use `google.protobuf.Timestamp`.

AIP-143

standard-codes Fields representing concepts with standardized codes must use them.
string-type Fields representing standardized codes must be strings.

AIP-144

http-body Add/Remove methods should use `*` as the HTTP body.
http-method Add/Remove methods must use the POST HTTP verb.
request-message-name Add/Remove methods must have standardized request message names.

AIP-146

any Avoid `google.protobuf.Any` fields.

AIP-148

declarative-friendly-fields Declarative-friendly resources must include some standard fields.
human-names Avoid imprecise terms for human names.

AIP-151

lro-metadata-reachable LRO metadata messages must be reachable.
lro-metadata-type LRO methods must have a metadata type.
lro-response-reachable LRO response messages must be reachable.
lro-response-type LRO methods must have a response type.
operation-info LRO methods must include an `operation_info` annotation.
response-unary Long-running operations must not use streaming.

AIP-154

declarative-friendly-required Declarative-friendly resources must have an etag field.
field-type Etag fields must be strings.
no-duplicate-etag Etag fields should not be set on request messages that include the resource.

AIP-156

forbidden-methods Singletons must not define List, Create, or Delete methods.

AIP-158

request-page-size-field Paginated RPCs must have a `page_size` field in the request.
request-page-token-field Paginated RPCs must have a `page_token` field in the request.
response-next-page-token-field Paginated RPCs must have a `next_page_token` field in the response.
response-plural-first-field First field of Paginated RPCs' response should be plural.
response-repeated-first-field First field (by both position and field number) of Paginated RPCs' response should be repeated.
response-unary Paginated responses must not use streaming.

AIP-159

hardcoded-hyphen Request URIs must not hard-code a `-` segment.

AIP-163

declarative-friendly-required Declarative-friendly mutations should have a validate_only field.
synonyms Change validation fields should be named `validate_only`.

AIP-164

declarative-friendly-required Declarative-friendly resources should have an Undelete method.
http-body Undelete methods should use `*` as the HTTP body.
http-method Undelete methods must use the POST HTTP verb.
http-uri-suffix Undelete methods must have the correct URI suffix
request-message-name Undelete methods must have standardized request message names.
request-name-behavior Undelete RPCs should annotate the `name` field with `google.api.field_behavior`.
request-name-field Undelete RPCs must have a `name` field in the request.
request-name-reference Undelete RPCs should annotate the `name` field with `google.api.resource_reference`.
request-unknown-fields Undelete RPCs should not have unexpected fields in the request.
response-lro Declarative-friendly undelete methods should use long-running operations.
response-message-name Undelete methods must return the resource.

AIP-165

http-body Purge methods should use `*` as the HTTP body.
http-method Purge methods must use the POST HTTP verb.
http-uri-suffix Purge methods must have the correct URI suffix
request-filter-behavior Purge requests should annotate the `filter` field with `google.api.field_behavior`.
request-filter-field Purge RPCs must have a `filter` field in the request.
request-force-field Purge RPCs must have a `force` field in the request.
request-message-name Purge methods must have standardized request message names.
request-parent-behavior Purge requests should annotate the `parent` field with `google.api.field_behavior`.
request-parent-field Purge RPCs must have a `parent` field in the request.
request-parent-reference Purge requests should annotate the `parent` field with `google.api.resource_reference`.
response-purge-count-field Purge RPCs must have a `purge_count` field in the response.
response-purge-sample-field Purge RPCs must have a `purge_sample` field in the response.
response-purge-sample-reference Purge responses should annotate the `purge_sample` field with `google.api.resource_reference`.

AIP-191

csharp-namespace The `option csharp_namespace` annotation should be idiomatic if set.
file-layout Proto files should follow a consistent layout.
file-option-consistency All proto files must set file packaging options consistently.
filenames Proto files must use reasonable filenames.
java-multiple-files All proto files must set `option java_multiple_files = true`.
java-outer-classname All proto files must set `option java_outer_classname`.
java-package All proto files must set `option java_package`.
php-namespace The `option php_namespace` annotation should be idiomatic if set.
proto-version All proto files must use proto3.
ruby-package The `option ruby_package` annotation should be idiomatic if set.

AIP-192

absolute-links Comments must use absolute links
has-comments Everything in a proto file must be commented.
no-html Comments must not use raw HTML
only-leading-comments All public comments should be leading comments.
trademarked-names Trademarked names should be used correctly.

AIP-203

immutable Immutable fields should be annotated.
input-only Input only fields should be annotated.
optional Optional fields may be annotated.
optional-conflict Optional fields must not have any other field behavior.
optional-consistency Optional fields should either be always or never annotated.
output-only Output only fields should be annotated.
required Required fields should be annotated.
required-and-optional Required fields must not use the optional keyword.

AIP-214

resource-expiry Resources with user-set expiry times should offer a ttl field.
ttl-type The `ttl` field should be a `google.protobuf.Duration`.

AIP-215

versioned-packages API-specific protos should be in versioned packages.

AIP-216

nesting Lifecycle state enums should be nested within the resource.
synonyms Lifecycle state enums should be called "State", not "Status".
value-synonyms Enforce common state values.

AIP-217

synonyms The field for unreachable resources should be named `unreachable`.
unreachable-field-type The unreachable field should be a repeated string.

AIP-231

http-body Batch Get methods must not have an HTTP body.
http-method Batch Get methods must use the GET HTTP verb.
http-uri-suffix Batch Get methods must have the correct URI suffix
plural-method-name Batch Get methods must have plural names.
request-message-name Batch Get methods must have standardized request message names.
request-names-behavior Batch Get requests should annotate the `names` field with `google.api.field_behavior`.
request-names-field Batch Get RPCs should have a `names` field in the request.
request-names-reference Batch Get requests should annotate the `names` field with `google.api.resource_reference`.
request-parent-field Batch Get RPCs must have a `parent` field in the request.
request-parent-reference Batch Get requests should annotate the `parent` field with `google.api.resource_reference`.
request-unknown-fields Batch Get RPCs should not have unexpected fields in the request.
response-message-name Batch Get methods must have standardized response message names.
response-resource-field Batch Get RPCs must have a repeated field for the resource in the response.

AIP-233

http-body Batch Create methods should use `*` as the HTTP body.
http-method Batch Create methods must use the POST HTTP verb.
http-uri-suffix Batch Create methods must have the correct URI suffix
plural-method-name Batch Create methods must have plural names.
request-message-name Batch Create methods must have standardized request message names.
request-parent-field Batch Create RPCs must have a `parent` field in the request.
request-parent-reference Batch Create requests should annotate the `parent` field with `google.api.resource_reference`.
request-requests-behavior Batch Create requests should annotate the `requests` field with `google.api.field_behavior`.
request-requests-field Batch Create RPCs should have a `requests` field in the request.
request-unknown-fields Batch Create RPCs should not have unexpected fields in the request.
response-message-name Batch Create methods must have standardized response message names.
response-resource-field Batch Create RPCs must have a repeated field for the resource in the response.

AIP-234

http-body Batch Update methods should use `*` as the HTTP body.
http-method Batch Update methods must use the POST HTTP verb.
http-uri-suffix Batch Update methods must have the correct URI suffix
plural-method-name Batch Update methods must have plural names.
request-message-name Batch Update methods must have standardized request message names.
request-parent-field Batch Update RPCs must have a `parent` field in the request.
request-parent-reference Batch Update requests should annotate the `parent` field with `google.api.resource_reference`.
request-requests-behavior Batch Update requests should annotate the `requests` field with `google.api.field_behavior`.
request-requests-field Batch Update RPCs should have a `requests` field in the request.
request-unknown-fields Batch Update RPCs should not have unexpected fields in the request.
response-message-name Batch Update methods must have standardized response message names.
response-resource-field Batch Update RPCs must have a repeated field for the resource in the response.

AIP-235

http-body Batch Delete methods should use `*` as the HTTP body.
http-method Batch Delete methods must use the POST HTTP verb.
http-uri-suffix Batch Delete methods must have the correct URI suffix
plural-method-name Batch Delete methods must have plural names.
request-message-name Batch Delete methods must have standardized request message names.
request-names-behavior Batch Delete requests should annotate the `names` field with `google.api.field_behavior`.
request-names-field Batch Delete RPCs should have a `names` field in the request.
request-names-reference Batch Delete requests should annotate the `names` field with `google.api.resource_reference`.
request-parent-field Batch Delete RPCs must have a `parent` field in the request.
request-parent-reference Batch Delete requests should annotate the `parent` field with `google.api.resource_reference`.
request-requests-behavior Batch Delete requests should annotate the `requests` field with `google.api.field_behavior`.
request-unknown-fields Batch Delete RPCs should not have unexpected fields in the request.
response-message-name Batch Delete methods must have standardized response message names.
response-resource-field Batch Delete RPCs must have a repeated field for the resource in the response.