Skip to content

Commit dc25e5e

Browse files
pkwarrenpkwarren
authored
Merge branch 'main' into dependabot/gradle/com.google.protobuf-protobuf-java-4.30.2
2 parents aaef9c5 + a8141d9 commit dc25e5e

File tree

50 files changed

+15798
-200
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+15798
-200
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@ assignees: ''
3636
- **Version**: <!--[e.g., macOS 10.15.7, Windows 10, Ubuntu 20.04]-->
3737
- **Compiler/Toolchain**: <!--[e.g., GCC 9.3.0, Clang 10.0.0]-->
3838
- **Protobuf Compiler & Version**: <!--[e.g. buf v1.17.0, protoc 3.17.3]-->
39-
- **Protoc-gen-validate Version**: <!--[if applicable, e.g., v0.6.1]-->
4039
- **Protovalidate Version**: <!--[if applicable, e.g., v1.0.2]-->
4140

4241
## Possible Solution

‎README.md

Lines changed: 90 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,131 @@
1-
# [![The Buf logo](.github/buf-logo.svg)][buf] protovalidate-java
1+
[![The Buf logo](.github/buf-logo.svg)][buf]
2+
3+
# protovalidate-java
24

35
[![CI](https://github.com/bufbuild/protovalidate-java/actions/workflows/ci.yaml/badge.svg)](https://github.com/bufbuild/protovalidate-java/actions/workflows/ci.yaml)
46
[![Conformance](https://github.com/bufbuild/protovalidate-java/actions/workflows/conformance.yaml/badge.svg)](https://github.com/bufbuild/protovalidate-java/actions/workflows/conformance.yaml)
57
[![BSR](https://img.shields.io/badge/BSR-Module-0C65EC)][buf-mod]
68

7-
`protovalidate-java` is the Java language implementation of [`protovalidate`](https://github.com/bufbuild/protovalidate) designed to validate Protobuf messages at runtime based on user-defined validation constraints. Powered by Google's Common Expression Language ([CEL](https://github.com/google/cel-spec)), it provides a flexible and efficient foundation for defining and evaluating custom validation rules. The primary goal of `protovalidate` is to help developers ensure data consistency and integrity across the network without requiring generated code.
9+
[Protovalidate][protovalidate] provides standard annotations to validate common constraints on messages and fields, as well as the ability to use [CEL][cel] to write custom constraints. It's the next generation of [protoc-gen-validate][protoc-gen-validate], the only widely used validation library for Protobuf.
810

9-
## The `protovalidate` project
11+
With Protovalidate, you can annotate your Protobuf messages with both standard and custom validation rules:
1012

11-
Head over to the core [`protovalidate`](https://github.com/bufbuild/protovalidate/) repository for:
13+
```protobuf
14+
syntax = "proto3";
1215
13-
- [The API definition](https://github.com/bufbuild/protovalidate/tree/main/proto/protovalidate/buf/validate/validate.proto): used to describe validation constraints
14-
- [Documentation](https://github.com/bufbuild/protovalidate/tree/main/docs): how to apply `protovalidate` effectively
15-
- [Migration tooling](https://github.com/bufbuild/protovalidate/tree/main/docs/migrate.md): incrementally migrate from `protoc-gen-validate`
16-
- [Conformance testing utilities](https://github.com/bufbuild/protovalidate/tree/main/docs/conformance.md): for acceptance testing of `protovalidate` implementations
16+
package banking.v1;
17+
18+
import "buf/validate/validate.proto";
1719
18-
Other `protovalidate` runtime implementations include:
20+
message MoneyTransfer {
21+
string to_account_id = 1 [
22+
// Standard rule: `to_account_id` must be a UUID
23+
(buf.validate.field).string.uuid = true
24+
];
1925
20-
- C++: [`protovalidate-cc`](https://github.com/bufbuild/protovalidate-cc)
21-
- Go: [`protovalidate-go`](https://github.com/bufbuild/protovalidate-go)
22-
- Python: [`protovalidate-python`](https://github.com/bufbuild/protovalidate-python)
26+
string from_account_id = 2 [
27+
// Standard rule: `from_account_id` must be a UUID
28+
(buf.validate.field).string.uuid = true
29+
];
2330
24-
And others coming soon:
31+
// Custom rule: `to_account_id` and `from_account_id` can't be the same.
32+
option (buf.validate.message).cel = {
33+
id: "to_account_id.not.from_account_id"
34+
message: "to_account_id and from_account_id should not be the same value"
35+
expression: "this.to_account_id != this.from_account_id"
36+
};
37+
}
38+
```
2539

26-
- TypeScript: `protovalidate-ts`
40+
Once you've added `protovalidate-java` to your project, validation is idiomatic Java:
41+
42+
```java
43+
ValidationResult result = validator.validate(message);
44+
if (!result.isSuccess()) {
45+
// Handle failure.
46+
}
47+
```
2748

2849
## Installation
2950

30-
To include `protovalidate-java` in your project, add the following to your build file:
51+
> [!TIP]
52+
> The easiest way to get started with Protovalidate for RPC APIs are the quickstarts in Buf's documentation. There's one available for [Java and gRPC][grpc-java].
53+
54+
`protovalidate-java` is listed in [Maven Central][maven], which provides installation snippets for Gradle, Maven, and other package managers. In Gradle, it's:
3155

3256
```gradle
3357
dependencies {
3458
implementation 'build.buf:protovalidate:<version>'
3559
}
3660
```
3761

38-
Remember to always check for the latest version of `protovalidate-java` on the project's [GitHub releases page](https://github.com/bufbuild/protovalidate-java/releases) to ensure you're using the most up-to-date version.
62+
## Documentation
3963

40-
## Usage
64+
Comprehensive documentation for Protovalidate is available in [Buf's documentation library][protovalidate].
4165

42-
### Implementing validation constraints
66+
Highlights for Java developers include:
4367

44-
Validation constraints are defined directly within `.proto` files. Documentation for adding constraints can be found in the `protovalidate` project [README](https://github.com/bufbuild/protovalidate) and its [comprehensive docs](https://github.com/bufbuild/protovalidate/tree/main/docs).
68+
* The [developer quickstart][quickstart]
69+
* A comprehensive RPC quickstart for [Java and gRPC][grpc-java]
70+
* A [migration guide for protoc-gen-validate][migration-guide] users
4571

46-
```protobuf
47-
syntax = "proto3";
72+
## Additional Languages and Repositories
4873

49-
package my.package;
74+
Protovalidate isn't just for Java! You might be interested in sibling repositories for other languages:
5075

51-
import "google/protobuf/timestamp.proto";
52-
import "buf/validate/validate.proto";
76+
- [`protovalidate-go`][pv-go] (Go)
77+
- [`protovalidate-python`][pv-python] (Python)
78+
- [`protovalidate-cc`][pv-cc] (C++)
79+
- `protovalidate-es` (TypeScript and JavaScript, coming soon!)
5380

54-
message Transaction {
55-
uint64 id = 1 [(buf.validate.field).uint64.gt = 999];
56-
google.protobuf.Timestamp purchase_date = 2;
57-
google.protobuf.Timestamp delivery_date = 3;
58-
59-
string price = 4 [(buf.validate.field).cel = {
60-
id: "transaction.price",
61-
message: "price must be positive and include a valid currency symbol ($ or £)",
62-
expression: "(this.startsWith('$') || this.startsWith('£')) && double(this.substring(1)) > 0"
63-
}];
64-
65-
option (buf.validate.message).cel = {
66-
id: "transaction.delivery_date",
67-
message: "delivery date must be after purchase date",
68-
expression: "this.delivery_date > this.purchase_date"
69-
};
70-
}
71-
```
81+
Additionally, [protovalidate's core repository](https://github.com/bufbuild/protovalidate) provides:
7282

73-
### Example
83+
- [Protovalidate's Protobuf API][validate-proto]
84+
- [Conformance testing utilities][conformance] for acceptance testing of `protovalidate` implementations
7485

75-
In your Java code, create an instance of the `Validator` class and use the `validate` method to validate your messages.
7686

77-
```java
78-
// Import the required packages
79-
package build.buf;
80-
81-
import build.buf.protovalidate.results.ValidationException;
82-
import build.buf.protovalidate.results.ValidationResult;
83-
import com.my.package.Transaction;
84-
import com.google.protobuf.Timestamp;
85-
86-
import build.buf.protovalidate.Validator;
87-
import build.buf.protovalidate.Config;
88-
89-
public class Main {
90-
91-
// Create timestamps for purchase and delivery date
92-
Timestamp purchaseDate = Timestamp.newBuilder().build();
93-
Timestamp deliveryDate = Timestamp.newBuilder().build();
94-
95-
// Create a transaction object using the Builder pattern
96-
Transaction transaction =
97-
Transaction.newBuilder()
98-
.setId(1234)
99-
.setPrice("$5.67")
100-
.setPurchaseDate(purchaseDate)
101-
.setDeliveryDate(deliveryDate)
102-
.build();
103-
104-
// Create a validator object with the default Configuration
105-
Validator validator = new Validator();
106-
// Validate the transaction object using the validator
107-
try {
108-
ValidationResult result = validator.validate(transaction);
109-
110-
// Check if there are any validation violations
111-
if (result.getViolations().isEmpty()) {
112-
// No violations, validation successful
113-
System.out.println("Validation succeeded");
114-
} else {
115-
// Print the violations if any found
116-
System.out.println(result.toString());
117-
}
118-
} catch (ValidationException e) {
119-
// Catch and print any ValidationExceptions thrown during the validation process
120-
System.out.println("Validation failed: " + e.getMessage());
121-
}
122-
}
123-
```
87+
## Contribution
88+
89+
We genuinely appreciate any help! If you'd like to contribute, check out these resources:
90+
91+
- [Contributing Guidelines][contributing]: Guidelines to make your contribution process straightforward and meaningful
92+
- [Conformance testing utilities](https://github.com/bufbuild/protovalidate/tree/main/docs/conformance.md): Utilities providing acceptance testing of `protovalidate` implementations
12493

125-
### Ecosystem
94+
## Related Sites
12695

127-
- [`protovalidate`](https://github.com/bufbuild/protovalidate) core repository
128-
- [Buf][buf]
129-
- [CEL Spec][cel-spec]
96+
- [Buf][buf]: Enterprise-grade Kafka and gRPC for the modern age
97+
- [Common Expression Language (CEL)][cel]: The open-source technology at the core of Protovalidate
13098

13199
## Legal
132100

133101
Offered under the [Apache 2 license][license].
134102

135-
[license]: LICENSE
136103
[buf]: https://buf.build
104+
[cel]: https://cel.dev
105+
106+
[pv-go]: https://github.com/bufbuild/protovalidate-go
107+
[pv-java]: https://github.com/bufbuild/protovalidate-java
108+
[pv-python]: https://github.com/bufbuild/protovalidate-python
109+
[pv-cc]: https://github.com/bufbuild/protovalidate-cc
110+
111+
[license]: LICENSE
112+
[contributing]: .github/CONTRIBUTING.md
137113
[buf-mod]: https://buf.build/bufbuild/protovalidate
138-
[cel-spec]: https://github.com/google/cel-spec
114+
115+
[protoc-gen-validate]: https://github.com/bufbuild/protoc-gen-validate
116+
117+
[protovalidate]: https://buf.build/docs/protovalidate
118+
[quickstart]: https://buf.build/docs/protovalidate/quickstart/
119+
[connect-go]: https://buf.build/docs/protovalidate/quickstart/connect-go/
120+
[grpc-go]: https://buf.build/docs/protovalidate/quickstart/grpc-go/
121+
[grpc-java]: https://buf.build/docs/protovalidate/quickstart/grpc-java/
122+
[grpc-python]: https://buf.build/docs/protovalidate/quickstart/grpc-python/
123+
[migration-guide]: https://buf.build/docs/migration-guides/migrate-from-protoc-gen-validate/
124+
125+
[maven]: https://central.sonatype.com/artifact/build.buf/protovalidate/overview
126+
[pkg-go]: https://pkg.go.dev/github.com/bufbuild/protovalidate-go
127+
128+
[validate-proto]: https://buf.build/bufbuild/protovalidate/docs/main:buf.validate
129+
[conformance]: https://github.com/bufbuild/protovalidate/blob/main/docs/conformance.md
130+
[examples]: https://github.com/bufbuild/protovalidate/tree/main/examples
131+
[migrate]: https://buf.build/docs/migration-guides/migrate-from-protoc-gen-validate/

‎conformance/expected-failures.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1020,3 +1020,28 @@ standard_constraints/ignore:
10201020
# message: "value must be greater than 0"
10211021
# field: "val" elements:{field_number:1 field_name:"val" field_type:TYPE_INT32}
10221022
# rule: "int32.gt" elements:{field_number:3 field_name:"int32" field_type:TYPE_MESSAGE} elements:{field_number:4 field_name:"gt" field_type:TYPE_INT32}
1023+
standard_constraints/required:
1024+
- proto/2023/message/explicit_presence/delimited/unset/ignore_always
1025+
- proto2/scalar/optional/unset/ignore_always
1026+
- proto3/scalar/optional/unset/ignore_always
1027+
- proto/2023/map/empty/ignore_always
1028+
- proto/2023/scalar/explicit_presence_with_default/unset/ignore_always
1029+
- proto2/oneof/other_member/ignore_always
1030+
- proto2/oneof/unset/ignore_always
1031+
- proto3/oneof/other_member/ignore_always
1032+
- proto/2023/repeated/expanded/empty/ignore_always
1033+
- proto/2023/oneof/unset/ignore_always
1034+
- proto/2023/message/explicit_presence/length_prefixed/unset/ignore_always
1035+
- proto/2023/scalar/explicit_presence/unset/ignore_always
1036+
- proto2/message/unset/ignore_always
1037+
- proto3/repeated/empty/ignore_always
1038+
- proto3/map/empty/ignore_always
1039+
- proto3/scalar/zero/ignore_always
1040+
- proto3/oneof/unset/ignore_always
1041+
- proto/2023/repeated/compact/empty/ignore_always
1042+
- proto2/repeated/empty/ignore_always
1043+
- proto/2023/scalar/implicit_presence/zero/ignore_always
1044+
- proto2/scalar/optional_with_default/unset/ignore_always
1045+
- proto2/map/empty/ignore_always
1046+
- proto3/message/unset/ignore_always
1047+
- proto/2023/oneof/other_member/ignore_always

0 commit comments

Comments
 (0)