https://github.com/bufbuild/protovalidate-es
Protocol Buffer Validation for ECMAScript
https://github.com/bufbuild/protovalidate-es
cel common-expression-language javascript protobuf protocol-buffers typescript
Last synced: 12 months ago
JSON representation
Protocol Buffer Validation for ECMAScript
- Host: GitHub
- URL: https://github.com/bufbuild/protovalidate-es
- Owner: bufbuild
- License: apache-2.0
- Created: 2025-04-28T17:19:16.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-24T17:11:55.000Z (12 months ago)
- Last Synced: 2025-06-24T18:27:04.774Z (12 months ago)
- Topics: cel, common-expression-language, javascript, protobuf, protocol-buffers, typescript
- Language: TypeScript
- Homepage:
- Size: 1.66 MB
- Stars: 43
- Watchers: 6
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[][buf]
# protovalidate-es
[](./LICENSE) [](https://www.npmjs.com/package/@bufbuild/protovalidate)
[Protovalidate][protovalidate] provides standard annotations to validate common rules on messages and fields, as well as the ability to use [CEL][cel] to write custom rules. It's the next generation of [protoc-gen-validate][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:
```protobuf
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 `@bufbuild/protovalidate` to your project, validation is simple:
```ts
import { create } from "@bufbuild/protobuf";
import { createValidator } from "@bufbuild/protovalidate";
import { MoneyTransferSchema } from "./gen/banking_pb";
const transfer = create(MoneyTransferSchema);
const validator = createValidator();
const result = validator.validate(MoneyTransferSchema, transfer);
if (result.kind !== "valid") {
// Handle failure.
}
```
> [!TIP]
>
> The `string.pattern` rule supports regular expressions with CEL's standard [RE2 syntax](https://github.com/google/re2/wiki/syntax).
>
> Protovalidate translates RE2 to ECMAScript's regular expressions. This works except for some RE2 flags, but it cannot support RE2's most important property: Execution in linear time, which guards against [ReDoS](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS).
>
> If you need full support for RE2, you can bring your own RE2 implementation:
>
> ```ts
> const validator = createValidator({
> regexMatch: (pattern: string, against: string): boolean => new RE2(pattern).test(against),
> });
> ```
## Packages
- [@bufbuild/protovalidate](https://www.npmjs.com/package/@bufbuild/protovalidate):
Validates Protobuf messages at runtime based on user-defined validation rules.
Note that protovalidate-es requires the Protobuf runtime [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf).
## Additional Languages and Repositories
Protovalidate isn't just for ECMAScript! You might be interested in sibling repositories for other languages:
- [`protovalidate-go`][pv-go] (Go)
- [`protovalidate-java`][pv-java] (Java)
- [`protovalidate-python`][pv-python] (Python)
- [`protovalidate-cc`][pv-cc] (C++)
Additionally, [protovalidate's core repository](https://github.com/bufbuild/protovalidate) provides:
- [Protovalidate's Protobuf API][validate-proto]
- [Example][examples] `.proto` files using `protovalidate`
- [Conformance testing utilities][conformance] for acceptance testing of `protovalidate` implementations
## Contribution
We genuinely appreciate any help! If you'd like to contribute, check out these resources:
- [Contributing Guidelines][contributing]: Guidelines to make your contribution process straightforward and meaningful
- [Conformance testing utilities](https://github.com/bufbuild/protovalidate/tree/main/docs/conformance.md): Utilities providing acceptance testing of `protovalidate` implementations
- [Protovalidate-ES conformance executor][conformance-executable]: Conformance testing executor
## Related Sites
- [Buf][buf]: Enterprise-grade Kafka and gRPC for the modern age
- [Common Expression Language (CEL)][cel]: The open-source technology at the core of Protovalidate
## Legal
Offered under the [Apache 2 license][license].
[buf]: https://buf.build
[cel]: https://cel.dev
[pv-go]: https://github.com/bufbuild/protovalidate-go
[pv-java]: https://github.com/bufbuild/protovalidate-java
[pv-python]: https://github.com/bufbuild/protovalidate-python
[pv-cc]: https://github.com/bufbuild/protovalidate-cc
[license]: LICENSE
[contributing]: .github/CONTRIBUTING.md
[protoc-gen-validate]: https://github.com/bufbuild/protoc-gen-validate
[protovalidate]: https://buf.build/docs/protovalidate
[quickstart]: https://buf.build/docs/protovalidate/quickstart/
[conformance-executable]: ./packages/protovalidate-testing/README.md
[validate-proto]: https://buf.build/bufbuild/protovalidate/docs/main:buf.validate
[conformance]: https://github.com/bufbuild/protovalidate/blob/main/docs/conformance.md
[examples]: https://github.com/bufbuild/protovalidate/tree/main/examples