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-121

[index]
no-mutable-cycles Resources must not form a resource reference cycle.
resource-must-support-get All resources must have a Standard Get method.
resource-must-support-list All resources must have a Standard List method.

AIP-122

[index]
camel-case-uris All resource names must use camel case in collection identifiers.
embedded-resource Resource references should not be embedded resources.
name-suffix Fields should not use the suffix `_name`.
no-self-links Resources should not contain self-links.
resource-collection-identifiers Resource patterns must use lowerCamelCase for collection identifiers.
resource-id-output-only Resource ID fields must be classified as `OUTPUT_ONLY`.
resource-reference-type All resource references must be strings.

AIP-123

[index]
duplicate-resource Resource types should not be defined more than once.
name-never-optional Resource name fields must never be labeled with proto3_optional.
resource-annotation Resource messages should be annotated with `google.api.resource`.
resource-definition-pattern Resource annotations should define a pattern.
resource-definition-type-name Resource type names must be of the form {Service Name}/{Type}.
resource-definition-variables Resource patterns should use consistent variable naming.
resource-name-components-alternate Resource name components should alternate between collection and identifiers.
resource-name-field Resource messages should have a `string name` field.
resource-pattern Resource annotations should define a pattern.
resource-pattern-plural Resource patterns must use the plural as the collection segment
resource-pattern-singular Resource patterns must use the singular as the resource ID segment
resource-plural Resource plural is required
resource-reference-type Resource reference annotations should only apply to strings.
resource-singular Resource singular is required and must be lowerCamelCase of type
resource-type-name Resource type names must be of the form {Service Name}/{Type}.
resource-variables Resource patterns should use consistent variable naming.

AIP-124

[index]
reference-same-package Resource references should refer to resources in the same package.

AIP-126

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

AIP-127

[index]
http-annotation HTTP annotations must be present on non-streaming methods.
http-template-pattern HTTP template variable patterns should match the patterns defined by their resources.
http-template-syntax HTTP patterns should follow the HTTP path template syntax.
resource-name-extraction HTTP annotations should extract full resource names into variables.
uri-leading-slash URIs should always begin with a leading slash.

AIP-128

[index]
resource-annotations-field Declarative-friendly resources must have an `annotations` field.
resource-reconciling-behavior Declarative-friendly resources should annotate the `reconciling` field as `OUTPUT_ONLY`.
resource-reconciling-field Declarative-friendly resources must have a `reconciling` field.

AIP-131

[index]
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-reference-type The `google.api.resource_reference` on the `name` field of a Get RPC request message should use `type`, not `child_type`.
request-name-required Get RPCs must have a `name` field in the request.
request-required-fields Get RPCs must not have unexpected required fields 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

[index]
http-body List methods must not have an HTTP body.
http-method List methods must use the GET HTTP verb.
http-uri-parent List methods must map the parent field to the URI.
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-parent-valid-reference List RPCs should reference the parent resource, not the listed resource.
request-required-fields List RPCs must not have unexpected required fields in the request.
request-show-deleted-required List requests must have a `show-deleted` field for resources supporting soft delete.
request-unknown-fields List RPCs should not have unexpected fields in the request.
resource-reference-type List should use a `child_type` reference to the paginated resource.
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

[index]
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.
http-uri-resource The collection where the resource is added should map to the URI path.
method-signature Create RPCs should annotate an appropriate method signature.
request-id-field 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-required-fields Create RPCs must not have unexpected required fields 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.
resource-reference-type Create should use a `child_type` reference to the created resource.
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

[index]
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-required-fields Update RPCs must not have unexpected required fields in the request.
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".
update-mask-optional-behavior Standard Update `update_mask` field must be `OPTIONAL`.

AIP-135

[index]
force-field Delete RPCs for resources with child collections should have a `force` field in the request.
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-force-field Delete request `force` fields must have type `bool`.
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-required-fields Delete RPCs must not have unexpected required fields 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

[index]
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.
request-message-name Custom methods must have standardized request message names.
response-message-name Custom methods must have standardized response message 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

[index]
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.
underscores Field names must not have goofy underscores.
uri Field names should prefer `uri` to `url`.

AIP-141

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

AIP-142

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

AIP-143

[index]
standardized-codes Fields representing concepts with standardized codes must use them.
string-type Fields representing standardized codes must be strings.

AIP-144

[index]
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

[index]
any Avoid `google.protobuf.Any` fields.

AIP-148

[index]
declarative-friendly-fields Declarative-friendly resources must include some standard fields.
field-behavior Standard resource fields should have the correct field behavior.
human-names Avoid imprecise terms for human names.
ip-address-format Annotate IP address fields with an IP address format.
uid-format Annotate uid with UUID4 format.
use-uid Use uid instead of id in resource messages.

AIP-151

[index]
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-152

[index]
http-body Run methods should use `*` as the HTTP body.
http-method Run methods must use the POST HTTP verb.
http-uri-suffix Run methods must have the correct URI suffix
request-message-name Run methods must have standardized request message names.
request-name-behavior Run requests should annotate the `name` field with `google.api.field_behavior`.
request-name-field Run RPCs must have a `name` field in the request.
request-name-reference Run requests should annotate the `name` field with `google.api.resource_reference`.
request-resource-suffix Run requests should identify a resource type which ends in "Job".
response-message-name Run methods must return a long-running operation.

AIP-154

[index]
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-155

[index]
request-id-format Annotate request_id with UUID4 format.

AIP-156

[index]
forbidden-methods Singletons must not define Create, or Delete methods.

AIP-157

[index]
request-read-mask-field Request read mask fields must have the correct type.

AIP-158

[index]
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.
request-skip-field Paginated RPC `skip` fields must have type `int32`.
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

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

AIP-162

[index]
commit-http-body Commit methods should use `*` as the HTTP body.
commit-http-method Commit methods must use the POST HTTP verb.
commit-http-uri-suffix Commit methods must have the correct URI suffix
commit-request-message-name Commit methods must have standardized request message names.
commit-request-name-behavior Commit requests should annotate the `name` field with `google.api.field_behavior`.
commit-request-name-field Commit RPCs must have a `name` field in the request.
commit-request-name-reference Commit requests should annotate the `name` field with `google.api.resource_reference`.
commit-response-message-name Commit methods must have standardized response message names.
delete-revision-http-body Delete Revision methods should not have an HTTP body.
delete-revision-http-method Delete Revision methods must use the DELETE HTTP verb.
delete-revision-http-uri-suffix Delete Revision methods must have the correct URI suffix
delete-revision-request-message-name Delete Revision methods must have standardized request message names.
delete-revision-request-name-behavior Delete Revision requests should annotate the `name` field with `google.api.field_behavior`.
delete-revision-request-name-field Delete Revision RPCs must have a `name` field in the request.
delete-revision-request-name-reference Delete Revision requests should annotate the `name` field with `google.api.resource_reference`.
delete-revision-response-message-name Delete Revision methods must return the resource.
rollback-http-body Rollback methods should use `*` as the HTTP body.
rollback-http-method Rollback methods must use the POST HTTP verb.
rollback-http-uri-suffix Rollback methods must have the correct URI suffix
rollback-request-message-name Rollback methods must have standardized request message names.
rollback-request-name-behavior Rollback requests should annotate the `name` field with `google.api.field_behavior`.
rollback-request-name-field Rollback RPCs must have a `name` field in the request.
rollback-request-name-reference Rollback requests should annotate the `name` field with `google.api.resource_reference`.
rollback-request-revision-id-behavior Rollback requests should annotate the `revision_id` field with `google.api.field_behavior`.
rollback-request-revision-id-field Rollback RPCs must have a `revision_id` field in the request.
rollback-response-message-name Rollback methods must have standardized response message names.
tag-revision-http-body Tag Revision methods should use `*` as the HTTP body.
tag-revision-http-method Tag Revision methods must use the POST HTTP verb.
tag-revision-http-uri-suffix Tag Revision methods must have the correct URI suffix
tag-revision-request-message-name Tag Revision methods must have standardized request message names.
tag-revision-request-name-behavior Tag Revision requests should annotate the `name` field with `google.api.field_behavior`.
tag-revision-request-name-field Tag Revision RPCs must have a `name` field in the request.
tag-revision-request-name-reference Tag Revision requests should annotate the `name` field with `google.api.resource_reference`.
tag-revision-request-tag-behavior Tag Revision requests should annotate the `tag` field with `google.api.field_behavior`.
tag-revision-request-tag-field Tag Revision RPCs must have a `tag` field in the request.
tag-revision-response-message-name Tag Revision methods must have standardized response message names.

AIP-163

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

AIP-164

[index]
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.
resource-expire-time-field Resources supporting soft delete must have an `expire_time` field.
response-lro Declarative-friendly undelete methods should use long-running operations.
response-message-name Undelete methods must return the resource.

AIP-165

[index]
http-body Purge methods should use `*` as the HTTP body.
http-method Purge methods must use the POST HTTP verb.
http-parent-variable Purge methods must map the parent field to the URI.
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-message-name Purge methods must return a long-running operation.
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

[index]
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-package Proto package must match the directory structure.
proto-version All proto files must use proto3.
ruby-package The `option ruby_package` annotation should be idiomatic if set.

AIP-192

[index]
absolute-links Comments must use absolute links
deprecated-comment Deprecated elements must have a corresponding comment.
has-comments Everything in a proto file must be commented.
no-html Comments must not use raw HTML
no-markdown-headings Public comments should not include Markdown headings.
no-markdown-tables Public comments should not include Markdown tables.
only-leading-comments All public comments should be leading comments.
trademarked-names Trademarked names should be used correctly.

AIP-202

[index]
string-only-format Certain field formats can only be applied to a string field.

AIP-203

[index]
field-behavior-required Field behavior is required, and must have one of OUTPUT_ONLY, REQUIRED, or OPTIONAL.
resource-identifier-only Only the resource's name field can have field behavior IDENTIFIER.
resource-name-identifier Resource name field must have field behavior IDENTIFIER.
unordered-list-repeated Only repeated fields may be annotated with `UNORDERED_LIST`.

AIP-214

[index]
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

[index]
versioned-packages API-specific protos should be in versioned packages.

AIP-216

[index]
nesting Lifecycle state enums should be nested within the resource.
state-field-output-only Lifecycle State enum fields should be marked OUTPUT_ONLY
synonyms Lifecycle state enums should be called "State", not "Status".
value-synonyms Enforce common state values.

AIP-217

[index]
return-partial-success-type The return_partial_success field should be a bool.
return-partial-success-with-unreachable The return_partial_success field should be paired with unreachable.
synonyms The field for unreachable resources should be named `unreachable`.
unreachable-field-type The unreachable field should be a repeated string.

AIP-231

[index]
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

[index]
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.
resource-reference-type BatchCreate should use a `child_type` reference to the created resource.
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

[index]
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

[index]
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.