buf.yaml

buf.yaml is used to define a module. It's the primary configuration file, and is responsible for the module's name, dependencies, and lint and breaking configuration

Type object
File match buf.yaml
Schema URL https://catalog.lintel.tools/schemas/schemastore/buf-yaml/latest.json
Source https://www.schemastore.org/buf.json

Validate with Lintel

npx @lintel/lintel check
Type: object

buf.yaml is used to define a module. It's the primary configuration file, and is responsible for the module's name, dependencies, and lint and breaking configuration.

Properties

version string required

The version key is required, and defines the current configuration version. The accepted values are v2, v1, and v1beta1.

Values: "v2" "v1" "v1beta1"

Definitions

lint-rule string

https://buf.build/docs/lint/rules

Examples:
  • "STANDARD"
  • "DEFAULT"
  • "BASIC"
  • "MINIMAL"
  • "COMMENTS"
  • "UNARY_RPC"
  • "DIRECTORY_SAME_PACKAGE"
  • "PACKAGE_DEFINED"
  • "PACKAGE_DIRECTORY_MATCH"
  • "PACKAGE_SAME_DIRECTORY"
  • "ENUM_PASCAL_CASE"
  • "ENUM_VALUE_UPPER_SNAKE_CASE"
  • "FIELD_LOWER_SNAKE_CASE"
  • "MESSAGE_PASCAL_CASE"
  • "ONEOF_LOWER_SNAKE_CASE"
  • "PACKAGE_LOWER_SNAKE_CASE"
  • "RPC_PASCAL_CASE"
  • "SERVICE_PASCAL_CASE"
  • "PACKAGE_SAME_CSHARP_NAMESPACE"
  • "PACKAGE_SAME_GO_PACKAGE"
  • "PACKAGE_SAME_JAVA_MULTIPLE_FILES"
  • "PACKAGE_SAME_JAVA_PACKAGE"
  • "PACKAGE_SAME_PHP_NAMESPACE"
  • "PACKAGE_SAME_RUBY_PACKAGE"
  • "PACKAGE_SAME_SWIFT_PREFIX"
  • "ENUM_FIRST_VALUE_ZERO"
  • "ENUM_NO_ALLOW_ALIAS"
  • "IMPORT_NO_WEAK"
  • "IMPORT_NO_PUBLIC"
  • "IMPORT_USED"
  • "ENUM_VALUE_PREFIX"
  • "ENUM_ZERO_VALUE_SUFFIX"
  • "FIELD_NOT_REQUIRED"
  • "FILE_LOWER_SNAKE_CASE"
  • "RPC_REQUEST_RESPONSE_UNIQUE"
  • "RPC_REQUEST_STANDARD_NAME"
  • "RPC_RESPONSE_STANDARD_NAME"
  • "PACKAGE_VERSION_SUFFIX"
  • "PROTOVALIDATE"
  • "SERVICE_SUFFIX"
  • "COMMENT_ENUM"
  • "COMMENT_ENUM_VALUE"
  • "COMMENT_FIELD"
  • "COMMENT_MESSAGE"
  • "COMMENT_ONEOF"
  • "COMMENT_RPC"
  • "COMMENT_SERVICE"
  • "RPC_NO_CLIENT_STREAMING"
  • "RPC_NO_SERVER_STREAMING"
  • "PACKAGE_NO_IMPORT_CYCLE"
  • "SYNTAX_SPECIFIED"
  • "STABLE_PACKAGE_NO_IMPORT_UNSTABLE"
breaking-rule string

https://buf.build/docs/breaking/rules

Examples:
  • "FILE"
  • "PACKAGE"
  • "WIRE_JSON"
  • "WIRE"
  • "ENUM_NO_DELETE"
  • "ENUM_SAME_JSON_FORMAT"
  • "ENUM_SAME_TYPE"
  • "ENUM_VALUE_NO_DELETE"
  • "ENUM_VALUE_NO_DELETE_UNLESS_NAME_RESERVED"
  • "ENUM_VALUE_NO_DELETE_UNLESS_NUMBER_RESERVED"
  • "ENUM_VALUE_SAME_NAME"
  • "EXTENSION_MESSAGE_NO_DELETE"
  • "EXTENSION_NO_DELETE"
  • "FIELD_NO_DELETE"
  • "FIELD_NO_DELETE_UNLESS_NAME_RESERVED"
  • "FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED"
  • "FIELD_SAME_CARDINALITY"
  • "FIELD_SAME_CPP_STRING_TYPE"
  • "FIELD_SAME_CTYPE"
  • "FIELD_SAME_DEFAULT"
  • "FIELD_SAME_JAVA_UTF8_VALIDATION"
  • "FIELD_SAME_JSON_NAME"
  • "FIELD_SAME_JSTYPE"
  • "FIELD_SAME_LABEL"
  • "FIELD_SAME_NAME"
  • "FIELD_SAME_ONEOF"
  • "FIELD_SAME_TYPE"
  • "FIELD_SAME_UTF8_VALIDATION"
  • "FIELD_WIRE_COMPATIBLE_CARDINALITY"
  • "FIELD_WIRE_COMPATIBLE_TYPE"
  • "FIELD_WIRE_JSON_COMPATIBLE_CARDINALITY"
  • "FIELD_WIRE_JSON_COMPATIBLE_TYPE"
  • "FILE_NO_DELETE"
  • "FILE_SAME_CC_ENABLE_ARENAS"
  • "FILE_SAME_CC_GENERIC_SERVICES"
  • "FILE_SAME_CSHARP_NAMESPACE"
  • "FILE_SAME_GO_PACKAGE"
  • "FILE_SAME_JAVA_GENERIC_SERVICES"
  • "FILE_SAME_JAVA_MULTIPLE_FILES"
  • "FILE_SAME_JAVA_OUTER_CLASSNAME"
  • "FILE_SAME_JAVA_PACKAGE"
  • "FILE_SAME_JAVA_STRING_CHECK_UTF8"
  • "FILE_SAME_OBJC_CLASS_PREFIX"
  • "FILE_SAME_OPTIMIZE_FOR"
  • "FILE_SAME_PACKAGE"
  • "FILE_SAME_PHP_CLASS_PREFIX"
  • "FILE_SAME_PHP_GENERIC_SERVICES"
  • "FILE_SAME_PHP_METADATA_NAMESPACE"
  • "FILE_SAME_PHP_NAMESPACE"
  • "FILE_SAME_PY_GENERIC_SERVICES"
  • "FILE_SAME_RUBY_PACKAGE"
  • "FILE_SAME_SWIFT_PREFIX"
  • "FILE_SAME_SYNTAX"
  • "MESSAGE_NO_DELETE"
  • "MESSAGE_NO_REMOVE_STANDARD_DESCRIPTOR_ACCESSOR"
  • "MESSAGE_SAME_JSON_FORMAT"
  • "MESSAGE_SAME_MESSAGE_SET_WIRE_FORMAT"
  • "MESSAGE_SAME_REQUIRED_FIELDS"
  • "ONEOF_NO_DELETE"
  • "PACKAGE_ENUM_NO_DELETE"
  • "PACKAGE_EXTENSION_NO_DELETE"
  • "PACKAGE_MESSAGE_NO_DELETE"
  • "PACKAGE_NO_DELETE"
  • "PACKAGE_SERVICE_NO_DELETE"
  • "RESERVED_ENUM_NO_DELETE"
  • "RESERVED_MESSAGE_NO_DELETE"
  • "RPC_NO_DELETE"
  • "RPC_SAME_CLIENT_STREAMING"
  • "RPC_SAME_IDEMPOTENCY_LEVEL"
  • "RPC_SAME_REQUEST_TYPE"
  • "RPC_SAME_RESPONSE_TYPE"
  • "RPC_SAME_SERVER_STREAMING"
  • "SERVICE_NO_DELETE"
lint-ignore-only object

Optional. Allows directories or files to be excluded from specific lint categories or rules. As with ignore, the paths must be relative to buf.yaml.

STANDARD string[]
DEFAULT string[]
BASIC string[]
MINIMAL string[]
COMMENTS string[]
UNARY_RPC string[]
DIRECTORY_SAME_PACKAGE string[]
PACKAGE_DEFINED string[]
PACKAGE_DIRECTORY_MATCH string[]
PACKAGE_SAME_DIRECTORY string[]
ENUM_PASCAL_CASE string[]
ENUM_VALUE_UPPER_SNAKE_CASE string[]
FIELD_LOWER_SNAKE_CASE string[]
MESSAGE_PASCAL_CASE string[]
ONEOF_LOWER_SNAKE_CASE string[]
PACKAGE_LOWER_SNAKE_CASE string[]
RPC_PASCAL_CASE string[]
SERVICE_PASCAL_CASE string[]
PACKAGE_SAME_CSHARP_NAMESPACE string[]
PACKAGE_SAME_GO_PACKAGE string[]
PACKAGE_SAME_JAVA_MULTIPLE_FILES string[]
PACKAGE_SAME_JAVA_PACKAGE string[]
PACKAGE_SAME_PHP_NAMESPACE string[]
PACKAGE_SAME_RUBY_PACKAGE string[]
PACKAGE_SAME_SWIFT_PREFIX string[]
ENUM_FIRST_VALUE_ZERO string[]
ENUM_NO_ALLOW_ALIAS string[]
IMPORT_NO_WEAK string[]
IMPORT_NO_PUBLIC string[]
IMPORT_USED string[]
ENUM_VALUE_PREFIX string[]
ENUM_ZERO_VALUE_SUFFIX string[]
FIELD_NOT_REQUIRED string[]
FILE_LOWER_SNAKE_CASE string[]
RPC_REQUEST_RESPONSE_UNIQUE string[]
RPC_REQUEST_STANDARD_NAME string[]
RPC_RESPONSE_STANDARD_NAME string[]
PACKAGE_VERSION_SUFFIX string[]
PROTOVALIDATE string[]
SERVICE_SUFFIX string[]
COMMENT_ENUM string[]
COMMENT_ENUM_VALUE string[]
COMMENT_FIELD string[]
COMMENT_MESSAGE string[]
COMMENT_ONEOF string[]
COMMENT_RPC string[]
COMMENT_SERVICE string[]
RPC_NO_CLIENT_STREAMING string[]
RPC_NO_SERVER_STREAMING string[]
PACKAGE_NO_IMPORT_CYCLE string[]
SYNTAX_SPECIFIED string[]
STABLE_PACKAGE_NO_IMPORT_UNSTABLE string[]
breaking-ignore-only object

Optional. Allows directories or files to be excluded from specific breaking change detection categories or rules. As with ignore, the paths must be relative to buf.yaml. We do not recommend this option in general.

FILE string[]
PACKAGE string[]
WIRE_JSON string[]
WIRE string[]
ENUM_NO_DELETE string[]
ENUM_SAME_JSON_FORMAT string[]
ENUM_SAME_TYPE string[]
ENUM_VALUE_NO_DELETE string[]
ENUM_VALUE_NO_DELETE_UNLESS_NAME_RESERVED string[]
ENUM_VALUE_NO_DELETE_UNLESS_NUMBER_RESERVED string[]
ENUM_VALUE_SAME_NAME string[]
EXTENSION_MESSAGE_NO_DELETE string[]
EXTENSION_NO_DELETE string[]
FIELD_NO_DELETE string[]
FIELD_NO_DELETE_UNLESS_NAME_RESERVED string[]
FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED string[]
FIELD_SAME_CARDINALITY string[]
FIELD_SAME_CPP_STRING_TYPE string[]
FIELD_SAME_CTYPE string[]
FIELD_SAME_DEFAULT string[]
FIELD_SAME_JAVA_UTF8_VALIDATION string[]
FIELD_SAME_JSON_NAME string[]
FIELD_SAME_JSTYPE string[]
FIELD_SAME_LABEL string[]
FIELD_SAME_NAME string[]
FIELD_SAME_ONEOF string[]
FIELD_SAME_TYPE string[]
FIELD_SAME_UTF8_VALIDATION string[]
FIELD_WIRE_COMPATIBLE_CARDINALITY string[]
FIELD_WIRE_COMPATIBLE_TYPE string[]
FIELD_WIRE_JSON_COMPATIBLE_CARDINALITY string[]
FIELD_WIRE_JSON_COMPATIBLE_TYPE string[]
FILE_NO_DELETE string[]
FILE_SAME_CC_ENABLE_ARENAS string[]
FILE_SAME_CC_GENERIC_SERVICES string[]
FILE_SAME_CSHARP_NAMESPACE string[]
FILE_SAME_GO_PACKAGE string[]
FILE_SAME_JAVA_GENERIC_SERVICES string[]
FILE_SAME_JAVA_MULTIPLE_FILES string[]
FILE_SAME_JAVA_OUTER_CLASSNAME string[]
FILE_SAME_JAVA_PACKAGE string[]
FILE_SAME_JAVA_STRING_CHECK_UTF8 string[]
FILE_SAME_OBJC_CLASS_PREFIX string[]
FILE_SAME_OPTIMIZE_FOR string[]
FILE_SAME_PACKAGE string[]
FILE_SAME_PHP_CLASS_PREFIX string[]
FILE_SAME_PHP_GENERIC_SERVICES string[]
FILE_SAME_PHP_METADATA_NAMESPACE string[]
FILE_SAME_PHP_NAMESPACE string[]
FILE_SAME_PY_GENERIC_SERVICES string[]
FILE_SAME_RUBY_PACKAGE string[]
FILE_SAME_SWIFT_PREFIX string[]
FILE_SAME_SYNTAX string[]
MESSAGE_NO_DELETE string[]
MESSAGE_NO_REMOVE_STANDARD_DESCRIPTOR_ACCESSOR string[]
MESSAGE_SAME_JSON_FORMAT string[]
MESSAGE_SAME_MESSAGE_SET_WIRE_FORMAT string[]
MESSAGE_SAME_REQUIRED_FIELDS string[]
ONEOF_NO_DELETE string[]
PACKAGE_ENUM_NO_DELETE string[]
PACKAGE_EXTENSION_NO_DELETE string[]
PACKAGE_MESSAGE_NO_DELETE string[]
PACKAGE_NO_DELETE string[]
PACKAGE_SERVICE_NO_DELETE string[]
RESERVED_ENUM_NO_DELETE string[]
RESERVED_MESSAGE_NO_DELETE string[]
RPC_NO_DELETE string[]
RPC_SAME_CLIENT_STREAMING string[]
RPC_SAME_IDEMPOTENCY_LEVEL string[]
RPC_SAME_REQUEST_TYPE string[]
RPC_SAME_RESPONSE_TYPE string[]
RPC_SAME_SERVER_STREAMING string[]
SERVICE_NO_DELETE string[]
v2-lint object

Optional. The lint settings you specify in this section are the default for all modules in the workspace, but can be replaced for individual modules by specifying different settings at the module level. Module-level settings have all of the same fields and behavior as workspace-level settings. If no lint settings are specified for the workspace, it uses the default settings.

use lint-rule[]

Optional. Lists the categories and/or specific rules to use. The STANDARD category is used if lint is unset.

Default:
[
  "STANDARD"
]
except lint-rule[]

Optional. Removes rules or categories from the use list.

ignore string[]

Optional. Excludes specific directories or files from all lint rules. If a directory is ignored, then all files and subfolders of the directory are also ignored. The specified paths must be relative to the buf.yaml file.

ignore_only object

Optional. Allows directories or files to be excluded from specific lint categories or rules. As with ignore, the paths must be relative to buf.yaml.

52 nested properties
STANDARD string[]
DEFAULT string[]
BASIC string[]
MINIMAL string[]
COMMENTS string[]
UNARY_RPC string[]
DIRECTORY_SAME_PACKAGE string[]
PACKAGE_DEFINED string[]
PACKAGE_DIRECTORY_MATCH string[]
PACKAGE_SAME_DIRECTORY string[]
ENUM_PASCAL_CASE string[]
ENUM_VALUE_UPPER_SNAKE_CASE string[]
FIELD_LOWER_SNAKE_CASE string[]
MESSAGE_PASCAL_CASE string[]
ONEOF_LOWER_SNAKE_CASE string[]
PACKAGE_LOWER_SNAKE_CASE string[]
RPC_PASCAL_CASE string[]
SERVICE_PASCAL_CASE string[]
PACKAGE_SAME_CSHARP_NAMESPACE string[]
PACKAGE_SAME_GO_PACKAGE string[]
PACKAGE_SAME_JAVA_MULTIPLE_FILES string[]
PACKAGE_SAME_JAVA_PACKAGE string[]
PACKAGE_SAME_PHP_NAMESPACE string[]
PACKAGE_SAME_RUBY_PACKAGE string[]
PACKAGE_SAME_SWIFT_PREFIX string[]
ENUM_FIRST_VALUE_ZERO string[]
ENUM_NO_ALLOW_ALIAS string[]
IMPORT_NO_WEAK string[]
IMPORT_NO_PUBLIC string[]
IMPORT_USED string[]
ENUM_VALUE_PREFIX string[]
ENUM_ZERO_VALUE_SUFFIX string[]
FIELD_NOT_REQUIRED string[]
FILE_LOWER_SNAKE_CASE string[]
RPC_REQUEST_RESPONSE_UNIQUE string[]
RPC_REQUEST_STANDARD_NAME string[]
RPC_RESPONSE_STANDARD_NAME string[]
PACKAGE_VERSION_SUFFIX string[]
PROTOVALIDATE string[]
SERVICE_SUFFIX string[]
COMMENT_ENUM string[]
COMMENT_ENUM_VALUE string[]
COMMENT_FIELD string[]
COMMENT_MESSAGE string[]
COMMENT_ONEOF string[]
COMMENT_RPC string[]
COMMENT_SERVICE string[]
RPC_NO_CLIENT_STREAMING string[]
RPC_NO_SERVER_STREAMING string[]
PACKAGE_NO_IMPORT_CYCLE string[]
SYNTAX_SPECIFIED string[]
STABLE_PACKAGE_NO_IMPORT_UNSTABLE string[]
disallow_comment_ignores boolean

Optional. Default is false if unset. If this option is set to true, you can't add leading comments within Protobuf files to ignore lint errors for certain components within the files. If the option is unset, for any line in a leading comment that starts with buf:lint:ignore <rule_id>, the linter ignores errors for that rule.

enum_zero_value_suffix string

Optional. Controls the behavior of the ENUM_ZERO_VALUE_SUFFIX lint rule. By default, this rule verifies that the zero value of all enums ends in _UNSPECIFIED, as recommended by the Google Protobuf Style Guide.

Default: "_UNSPECIFIED"
rpc_allow_same_request_response boolean

Optional. Allows the same message type to be used for a single RPC's request and response type. We don't recommend using this option.

rpc_allow_google_protobuf_empty_requests boolean

Optional. Allows RPC requests to be google.protobuf.Empty messages. You can set this if you want to allow messages to be void forever and never take any parameters. We don't recommend using this option.

rpc_allow_google_protobuf_empty_responses boolean

Optional. Allows RPC responses to be google.protobuf.Empty messages. You can set this if you want to allow messages to never return any parameters. We don't recommend using this option.

service_suffix string

Optional. Controls the behavior of the SERVICE_SUFFIX lint rule. By default, this rule verifies that all service names are suffixed with Service.

Default: "Service"
v2-breaking object

Optional. Specifies the breaking change detection rules enforced on the Protobuf files in the directory.

use breaking-rule[]

Optional. Lists the rules or categories to use for breaking change detection. The FILE category is used if breaking is unset, which is conservative and appropriate for most teams.

Default:
[
  "FILE"
]
except breaking-rule[]

Optional. Removes rules or categories from the use list. We don't recommend using this option.

ignore string[]

Optional. Excludes specific directories or files from all breaking change detection rules. If a directory is ignored, then all files and subfolders of the directory are also ignored. The specified paths must be relative to the buf.yaml file. This option can be useful for ignoring packages that are in active development but not deployed in production, especially alpha or beta packages. If you want to ignore all alpha,beta, or test packages, we recommend using the ignore_unstable_packages setting instead.

ignore_only object

Optional. Allows directories or files to be excluded from specific breaking change detection categories or rules. As with ignore, the paths must be relative to buf.yaml. We do not recommend this option in general.

73 nested properties
FILE string[]
PACKAGE string[]
WIRE_JSON string[]
WIRE string[]
ENUM_NO_DELETE string[]
ENUM_SAME_JSON_FORMAT string[]
ENUM_SAME_TYPE string[]
ENUM_VALUE_NO_DELETE string[]
ENUM_VALUE_NO_DELETE_UNLESS_NAME_RESERVED string[]
ENUM_VALUE_NO_DELETE_UNLESS_NUMBER_RESERVED string[]
ENUM_VALUE_SAME_NAME string[]
EXTENSION_MESSAGE_NO_DELETE string[]
EXTENSION_NO_DELETE string[]
FIELD_NO_DELETE string[]
FIELD_NO_DELETE_UNLESS_NAME_RESERVED string[]
FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED string[]
FIELD_SAME_CARDINALITY string[]
FIELD_SAME_CPP_STRING_TYPE string[]
FIELD_SAME_CTYPE string[]
FIELD_SAME_DEFAULT string[]
FIELD_SAME_JAVA_UTF8_VALIDATION string[]
FIELD_SAME_JSON_NAME string[]
FIELD_SAME_JSTYPE string[]
FIELD_SAME_LABEL string[]
FIELD_SAME_NAME string[]
FIELD_SAME_ONEOF string[]
FIELD_SAME_TYPE string[]
FIELD_SAME_UTF8_VALIDATION string[]
FIELD_WIRE_COMPATIBLE_CARDINALITY string[]
FIELD_WIRE_COMPATIBLE_TYPE string[]
FIELD_WIRE_JSON_COMPATIBLE_CARDINALITY string[]
FIELD_WIRE_JSON_COMPATIBLE_TYPE string[]
FILE_NO_DELETE string[]
FILE_SAME_CC_ENABLE_ARENAS string[]
FILE_SAME_CC_GENERIC_SERVICES string[]
FILE_SAME_CSHARP_NAMESPACE string[]
FILE_SAME_GO_PACKAGE string[]
FILE_SAME_JAVA_GENERIC_SERVICES string[]
FILE_SAME_JAVA_MULTIPLE_FILES string[]
FILE_SAME_JAVA_OUTER_CLASSNAME string[]
FILE_SAME_JAVA_PACKAGE string[]
FILE_SAME_JAVA_STRING_CHECK_UTF8 string[]
FILE_SAME_OBJC_CLASS_PREFIX string[]
FILE_SAME_OPTIMIZE_FOR string[]
FILE_SAME_PACKAGE string[]
FILE_SAME_PHP_CLASS_PREFIX string[]
FILE_SAME_PHP_GENERIC_SERVICES string[]
FILE_SAME_PHP_METADATA_NAMESPACE string[]
FILE_SAME_PHP_NAMESPACE string[]
FILE_SAME_PY_GENERIC_SERVICES string[]
FILE_SAME_RUBY_PACKAGE string[]
FILE_SAME_SWIFT_PREFIX string[]
FILE_SAME_SYNTAX string[]
MESSAGE_NO_DELETE string[]
MESSAGE_NO_REMOVE_STANDARD_DESCRIPTOR_ACCESSOR string[]
MESSAGE_SAME_JSON_FORMAT string[]
MESSAGE_SAME_MESSAGE_SET_WIRE_FORMAT string[]
MESSAGE_SAME_REQUIRED_FIELDS string[]
ONEOF_NO_DELETE string[]
PACKAGE_ENUM_NO_DELETE string[]
PACKAGE_EXTENSION_NO_DELETE string[]
PACKAGE_MESSAGE_NO_DELETE string[]
PACKAGE_NO_DELETE string[]
PACKAGE_SERVICE_NO_DELETE string[]
RESERVED_ENUM_NO_DELETE string[]
RESERVED_MESSAGE_NO_DELETE string[]
RPC_NO_DELETE string[]
RPC_SAME_CLIENT_STREAMING string[]
RPC_SAME_IDEMPOTENCY_LEVEL string[]
RPC_SAME_REQUEST_TYPE string[]
RPC_SAME_RESPONSE_TYPE string[]
RPC_SAME_SERVER_STREAMING string[]
SERVICE_NO_DELETE string[]
ignore_unstable_packages boolean

Optional. Ignores packages with a last component that's one of the unstable forms recognized by the Buf linter's PACKAGE_VERSION_SUFFIX rule.