protovalidate-cc

Protovalidate provides standard annotations to validate common constraints on messages and fields, as well as the ability to use CEL to write custom constraints. It's the next generation of protoc-gen-validate, the only widely used validation library for Protobuf.

With Protovalidate, you can annotate your Protobuf messages with both standard and custom validation rules:

syntax = "proto3";

package banking.v1;

import "buf/validate/validate.proto";

message MoneyTransfer {
  string to_account_id = 1 [
    // Standard rule: `to_account_id` must be a UUID
    (buf.validate.field).string.uuid = true
  ];

  string from_account_id = 2 [
    // Standard rule: `from_account_id` must be a UUID
    (buf.validate.field).string.uuid = true
  ];

  // Custom rule: `to_account_id` and `from_account_id` can't be the same.
  option (buf.validate.message).cel = {
    id: "to_account_id.not.from_account_id"
    message: "to_account_id and from_account_id should not be the same value"
    expression: "this.to_account_id != this.from_account_id"
  };
}

Once you've added protovalidate-cc to your project, validation is idiomatic C++:

std::unique_ptr<buf::validate::ValidatorFactory> factory =
  buf::validate::ValidatorFactory::New().value();
google::protobuf::Arena arena;
buf::validate::Validator validator = factory->NewValidator(&arena);
buf::validate::Violations results = validator.Validate(moneyTransfer).value();
if (results.violations_size() > 0) {
    // Handle failure
}

Installation

Building from source

To install protovalidate-cc, clone the repository and build the project:

git clone https://github.com/bufbuild/protovalidate-cc.git
cd protovalidate-cc
make build

Remember to always check for the latest version of protovalidate-cc on the project's GitHub releases page to ensure you're using the most up-to-date version.

Bazel external repository

Workspace

To use protovalidate-cc as an external Bazel repository, add the following to the WORKSPACE file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "com_github_bufbuild_protovalidate_cc",
    sha256 = ...,
    strip_prefix = "protovalidate-cc-{verion}",
    urls = [
        "https://github.com/bufbuild/protovalidate-cc/archive/v{verion}.tar.gz",
    ],
)

load("@com_github_bufbuild_protovalidate_cc//bazel:deps.bzl", "protovalidate_cc_dependencies")

protovalidate_cc_dependencies()

Then add a dependency to a cc_library or cc_binary target:

cc_library(
    ...
    deps = [
        "@com_github_bufbuild_protovalidate_cc//buf/validate:validator",
        ...
    ]
)

Bzlmod

To use protovalidate-cc as an external dependency for bzlmod, add the following to the MODULE.bazel:

module(
    name = "my-module",
    version = "1.0",
)

bazel_dep(name = "cel-cpp", repo_name = "com_google_cel_cpp", version="0.11.0")
bazel_dep(name = "protovalidate-cc", version = "0.6.0")

# Required because cel-cpp is not in the BCR.
git_override(
  module_name = "cel-cpp",
  remote = "https://github.com/google/cel-cpp.git",
  commit = "<commit hash>"
)

# Required becaquse protovalidate-cc isn't in the BCR, since it depends on cel-cpp.
git_override(
  module_name = "protovalidate-cc",
  remote = "https://github.com/bufbuild/protovalidate-cc.git",
  commit = "<commit hash>"
)

And the following to your BUILD.bazel:

cc_binary(
   ...
   deps = [ ..., "@protovalidate-cc//buf/validate:validator", ...]
   ...
)

Documentation

Comprehensive documentation for Protovalidate is available in Buf's documentation library.

Highlights for C++ developers include:

• The developer quickstart
• A migration guide for protoc-gen-validate users

Additional Languages and Repositories

Protovalidate isn't just for C++! You might be interested in sibling repositories for other languages:

• protovalidate-go (Go)
• protovalidate-java (Java)
• protovalidate-python (Python)
• protovalidate-es (TypeScript and JavaScript)

Additionally, protovalidate's core repository provides:

• Protovalidate's Protobuf API
• Conformance testing utilities for acceptance testing of protovalidate implementations

Contribution

We genuinely appreciate any help! If you'd like to contribute, check out these resources:

• Contributing Guidelines: Guidelines to make your contribution process straightforward and meaningful
• Conformance testing utilities: Utilities providing acceptance testing of protovalidate implementations

Related Sites

• Buf: Enterprise-grade Kafka and gRPC for the modern age
• Common Expression Language (CEL): The open-source technology at the core of Protovalidate

Legal

Offered under the Apache 2 license.