protovalidate-cc

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

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

syntax = "proto3";

package acme.user.v1;

import "buf/validate/validate.proto";

message User {
  string id = 1 [(buf.validate.field).string.uuid = true];
  uint32 age = 2 [(buf.validate.field).uint32.lte = 150]; // We can only hope.
  string email = 3 [(buf.validate.field).string.email = true];
  string first_name = 4 [(buf.validate.field).string.max_len = 64];
  string last_name = 5 [(buf.validate.field).string.max_len = 64];

  option (buf.validate.message).cel = {
    id: "first_name_requires_last_name"
    message: "last_name must be present if first_name is present"
    expression: "!has(this.first_name) || has(this.last_name)"
  };
}

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-{version}",
    urls = [
        "https://github.com/bufbuild/protovalidate-cc/releases/download/v{version}/protovalidate-cc-{version}.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 = "1.0.0-rc.2")

And the following to your BUILD.bazel:

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

Documentation

Comprehensive documentation for Protovalidate is available at protovalidate.com.

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

Contributing

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

Legal

Offered under the Apache 2 license.