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-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".

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.
`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]
`standard-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]
`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.