buf.json

{
  "$comment": "https://buf.build/docs/configuration/v1/buf-yaml",
  "$id": "https://json.schemastore.org/buf.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "buf.yaml",
  "description": "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",
  "$defs": {
    "lint-rule": {
      "type": "string",
      "description": "https://buf.build/docs/lint/rules",
      "enum": [
        "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",
        "FILE_LOWER_SNAKE_CASE",
        "RPC_REQUEST_RESPONSE_UNIQUE",
        "RPC_REQUEST_STANDARD_NAME",
        "RPC_RESPONSE_STANDARD_NAME",
        "PACKAGE_VERSION_SUFFIX",
        "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"
      ]
    },
    "breaking-rule": {
      "type": "string",
      "description": "https://buf.build/docs/breaking/rules",
      "enum": ["FILE", "PACKAGE", "WIRE_JSON", "WIRE"]
    }
  },
  "required": ["version"],
  "properties": {
    "version": {
      "description": "The version key is required, and defines the current configuration version. The only accepted values are v1beta1 and v1.",
      "type": "string",
      "enum": ["v1", "v1beta1"]
    },
    "name": {
      "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#name",
      "description": "The name is optional, and uniquely identifies your module. The name must be a valid module name and is directly associated with the repository that owns it.",
      "type": "string"
    },
    "deps": {
      "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#deps",
      "description": "The deps key is optional, and declares one or more modules that your module depends on. Each deps entry must be a module reference, and, is directly associated with a repository, as well as a reference, which is either a tag or commit.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "build": {
      "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#build",
      "description": "The build key is optional, and is used to control how buf builds modules.",
      "type": "object",
      "properties": {
        "excludes": {
          "description": "The excludes key is optional, and lists directories to ignore from .proto file discovery. Any directories added to this list are completely skipped and excluded in the module. We do not recommend using this option in general, however in some situations it is unavoidable.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "lint": {
      "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#lint",
      "description": "The lint key is optional, and specifies the lint rules enforced on the files in the module. See https://buf.build/docs/lint/rules.",
      "type": "object",
      "properties": {
        "use": {
          "description": "The use key is optional, and lists the IDs or categories to use for linting.",
          "type": "array",
          "default": ["DEFAULT"],
          "items": {
            "$ref": "#/$defs/lint-rule"
          }
        },
        "except": {
          "description": "The except key is optional, and removes IDs or categories from the use list.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/lint-rule"
          }
        },
        "ignore": {
          "description": "The ignore key is optional, and allows directories or files to be excluded from all lint rules when running buf lint. If a directory is ignored, then all files and subfolders of the directory will also be ignored. The specified directory or file paths must be relative to the buf.yaml.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "ignore_only": {
          "$comment": "All of the #/$defs/lint-rule values can be keys",
          "description": "The ignore_only key is optional, and allows directories or files to be excluded from specific lint rules when running buf lint by taking a map from lint rule ID or category to path. As with ignore, the paths must be relative to the buf.yaml.",
          "type": "object",
          "properties": {
            "DEFAULT": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "BASIC": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "MINIMAL": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENTS": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "UNARY_RPC": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "DIRECTORY_SAME_PACKAGE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_DEFINED": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_DIRECTORY_MATCH": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_DIRECTORY": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ENUM_PASCAL_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ENUM_VALUE_UPPER_SNAKE_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "FIELD_LOWER_SNAKE_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "MESSAGE_PASCAL_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ONEOF_LOWER_SNAKE_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_LOWER_SNAKE_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "RPC_PASCAL_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "SERVICE_PASCAL_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_CSHARP_NAMESPACE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_GO_PACKAGE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_JAVA_MULTIPLE_FILES": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_JAVA_PACKAGE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_PHP_NAMESPACE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_RUBY_PACKAGE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_SAME_SWIFT_PREFIX": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ENUM_FIRST_VALUE_ZERO": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ENUM_NO_ALLOW_ALIAS": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "IMPORT_NO_WEAK": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "IMPORT_NO_PUBLIC": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "IMPORT_USED": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ENUM_VALUE_PREFIX": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "ENUM_ZERO_VALUE_SUFFIX": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "FILE_LOWER_SNAKE_CASE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "RPC_REQUEST_RESPONSE_UNIQUE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "RPC_REQUEST_STANDARD_NAME": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "RPC_RESPONSE_STANDARD_NAME": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_VERSION_SUFFIX": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "SERVICE_SUFFIX": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_ENUM": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_ENUM_VALUE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_FIELD": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_MESSAGE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_ONEOF": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_RPC": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "COMMENT_SERVICE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "RPC_NO_CLIENT_STREAMING": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "RPC_NO_SERVER_STREAMING": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE_NO_IMPORT_CYCLE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false
        },
        "allow_comment_ignores": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#allow_comment_ignores",
          "description": "The allow_comment_ignores key is optional, and turns on comment-driven ignores. We do not recommend using this option in general, however in some situations it is unavoidable. See https://buf.build/docs/configuration/v1/buf-yaml#allow_comment_ignores.",
          "type": "boolean",
          "default": false
        },
        "enum_zero_value_suffix": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#enum_zero_value_suffix",
          "description": "The enum_zero_value_suffix key is optional, and controls the behavior of the ENUM_ZERO_VALUE_SUFFIX lint rule. See https://buf.build/docs/configuration/v1/buf-yaml#enum_zero_value_suffix.",
          "type": "string",
          "default": "_UNSPECIFIED"
        },
        "rpc_allow_same_request_response": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#rpc_allow_same_request_response",
          "description": "The rpc_allow_same_request_response key is optional, and allows the same message type to be used for a single RPC's request and response type. We do not recommend using this option in general.",
          "type": "boolean",
          "default": false
        },
        "rpc_allow_google_protobuf_empty_requests": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#rpc_allow_google_protobuf_empty_requests",
          "description": "The rpc_allow_google_protobuf_empty_requests key is optional, and allows RPC requests to be google.protobuf.Empty messages. This can be set if you want to allow messages to be void forever, that is, to never take any parameters. We do not recommend using this option in general.",
          "type": "boolean",
          "default": false
        },
        "rpc_allow_google_protobuf_empty_responses": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#rpc_allow_google_protobuf_empty_responses",
          "description": "The rpc_allow_google_protobuf_empty_responses key is optional, and allows RPC responses to be google.protobuf.Empty messages. This can be set if you want to allow messages to never return any parameters. We do not recommend using this option in general.",
          "type": "boolean",
          "default": false
        },
        "service_suffix": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#service_suffix",
          "description": "The service_suffix key is optional, and controls the behavior of the SERVICE_SUFFIX lint rule. See https://buf.build/docs/configuration/v1/buf-yaml#service_suffix.",
          "type": "string",
          "default": "Service"
        }
      }
    },
    "breaking": {
      "description": "The breaking key is optional, and specifies the breaking change detection rules enforced on the files contained within the module.",
      "type": "object",
      "properties": {
        "use": {
          "description": "The use key is optional, and lists the IDs or categories to use for breaking change detection. The default value is the single item FILE, which is what we recommend.",
          "type": "array",
          "default": ["FILE"],
          "items": {
            "$ref": "#/$defs/breaking-rule"
          }
        },
        "except": {
          "description": "The except key is optional, and removes IDs or categories from the use list. We do not recommend using this option in general.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/breaking-rule"
          }
        },
        "ignore": {
          "description": "The ignore key is optional, and allows directories or files to be excluded from all breaking rules when running buf breaking. If a directory is ignored, then all files and subfolders of the directory will also be ignored. The specified directory or file paths must be relative to the buf.yaml. This option can be useful for ignoring packages that are in active development but not deployed in production, especially alpha or beta packages, and we expect ignore to be commonly used for this case.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "ignore_only": {
          "$comment": "All of the #/$defs/breaking-rule values can be keys.",
          "description": "The ignore_only key is optional, and allows directories or files to be excluded from specific breaking rules when running buf breaking by taking a map from breaking rule ID or category to path. As with ignore, the paths must be relative to the buf.yaml. We do not recommend this option in general.",
          "type": "object",
          "properties": {
            "FILE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "PACKAGE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "WIRE_JSON": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "WIRE": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false
        },
        "ignore_unstable_packages": {
          "$comment": "https://buf.build/docs/configuration/v1/buf-yaml#ignore_unstable_packages",
          "description": "The ignore_unstable_packages key is optional, and ignores packages with a last component that is one of the unstable forms recognized by PACKAGE_VERSION_SUFFIX.",
          "type": "boolean",
          "default": false
        }
      }
    }
  }
}