Skip to content

Commit 194c9c0

Browse files
jrinehart-bufrakuista
jrinehart-buf
and
rakuista
authored
Prepare GitHub docs for shift to buf.build/docs (#317)
Notes for reviewers: * There are no code changes here: purely Markdown. It's probably easiest to view the updates pages by [opening the branch](https://github.com/bufbuild/protovalidate/tree/jrinehart/dvrl-62-update-protovalidate-repository) in a second browser tab. This PR: * Updates the README for Protovalidate to be in "hierarchy of developer needs" order intended to be consistent across all Protovalidate repositories: 1. What's Protovalidate? 2. How do I install it or find support for my language? (Supported Languages) 3. How do I use it? (Documentation) 4. How do I contribute? (Contribution) 5. Related Sites 6. Legal * Updates other Markdown files in this repo to: * Where necessary, provide "This page has moved..." style pointers to new pages in buf.build/docs. * Use a consistent title format with the Buf logo --------- Co-authored-by: Carol Gunby <[email protected]>
1 parent 547a1e2 commit 194c9c0

File tree

93 files changed

+141
-4066
lines changed

Some content is hidden

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

93 files changed

+141
-4066
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

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

4140
## Possible Solution

‎README.md‎

Lines changed: 63 additions & 217 deletions
Original file line numberDiff line numberDiff line change
@@ -1,258 +1,104 @@
1-
![The Buf logo](https://raw.githubusercontent.com/bufbuild/protovalidate/main/.github/buf-logo.svg)
1+
![The Buf logo](https://raw.githubusercontent.com/bufbuild/protovalidate/main/.github/buf-logo.svg)
22

3-
# protovalidate
3+
# Protovalidate
44

55
[![CI](https://github.com/bufbuild/protovalidate/actions/workflows/ci.yaml/badge.svg?branch=main)][ci]
66
[![Slack](https://img.shields.io/badge/Slack-Buf-%23e01563)][slack]
77
[![BSR](https://img.shields.io/badge/BSR-Module-0C65EC)][buf-mod]
88

9-
`protovalidate` is a series of libraries designed to validate Protobuf messages at
10-
runtime based on user-defined validation rules. Powered by Google's Common
11-
Expression Language ([CEL][cel-spec]), it provides a
12-
flexible and efficient foundation for defining and evaluating custom validation
13-
rules. The primary goal of `protovalidate` is to help developers ensure data
14-
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.
1510

16-
> [!NOTE]
17-
> If you are migrating from [protoc-gen-validate][pgv], read our [migration guide][migration-guide].
18-
19-
## What is this repository?
20-
21-
This repository is the core of the `protovalidate` project. It contains:
22-
23-
- [The API definition][validate-proto]: used to describe validation constraints
24-
- [Documentation][docs]: how to apply `protovalidate` effectively
25-
- [Migration tooling][migrate]: incrementally migrate from `protoc-gen-validate`
26-
- [Examples][examples]: example `.proto` files using `protovalidate`
27-
- [Conformance testing utilities][conformance]: for acceptance testing of `protovalidate` implementations
28-
29-
### Implementations
30-
31-
Runtime implementations of `protovalidate` can be found in their own repositories:
32-
33-
- Go: [`protovalidate-go`][pv-go] (beta release)
34-
- C++: [`protovalidate-cc`][pv-cc] (beta release)
35-
- Java: [`protovalidate-java`][pv-java] (beta release)
36-
- Python: [`protovalidate-python`][pv-python] (beta release)
37-
- TypeScript: `protovalidate-ts` (coming soon)
38-
39-
Interested in adding support for another language? Check out our
40-
[Contributing Guidelines][contributing].
41-
42-
## Usage
43-
44-
### Import protovalidate
45-
46-
To define constraints within your Protobuf messages,
47-
import `buf/validate/validate.proto` into your `.proto` files:
11+
With Protovalidate, you can annotate your Protobuf messages with both standard and custom validation rules:
4812

4913
```protobuf
5014
syntax = "proto3";
5115
52-
package my.package;
16+
package banking.v1;
5317
5418
import "buf/validate/validate.proto";
55-
```
56-
57-
#### Build with [`buf`][buf]
5819
59-
Add a dependency on [`buf.build/bufbuild/protovalidate`][buf-mod] to your
60-
module's [`buf.yaml`][buf-deps]:
61-
62-
```yaml
63-
version: v1
64-
# <snip>
65-
deps:
66-
- buf.build/bufbuild/protovalidate
67-
# <snip>
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+
];
25+
26+
string from_account_id = 2 [
27+
// Standard rule: `from_account_id` must be a UUID
28+
(buf.validate.field).string.uuid = true
29+
];
30+
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+
}
6838
```
6939

70-
After modifying your `buf.yaml`, don't forget to run `buf mod update` to ensure
71-
your dependencies are up-to-date.
72-
73-
#### Build with `protoc`
74-
75-
Add an import path (`-I` flag) pointing to the contents of the `proto/protovalidate`
76-
directory to your invocation of `protoc`:
77-
78-
```shell
79-
protoc \
80-
-I ./vendor/protovalidate/proto/protovalidate \
81-
# <snip>
82-
```
83-
84-
### Implementing validation constraints
85-
86-
Validation constraints can be enforced using the `buf.validate` Protobuf package. The rules are specified directly in the `.proto` files.
87-
88-
Let's consider a few examples:
89-
90-
1. **Scalar field validation:** For a basic `User` message, we can enforce constraints such as a minimum length for the user's name.
91-
92-
```protobuf
93-
syntax = "proto3";
94-
95-
import "buf/validate/validate.proto";
96-
97-
message User {
98-
// User's name, must be at least 1 character long.
99-
string name = 1 [(buf.validate.field).string.min_len = 1];
100-
}
101-
```
102-
103-
2. **Map field validation:** For a `Product` message with a map of item quantities, we can ensure that all quantities are positive.
104-
105-
```protobuf
106-
syntax = "proto3";
107-
108-
import "buf/validate/validate.proto";
109-
110-
message Product {
111-
// Map of item quantities, all quantities must be positive.
112-
map<string, int32> item_quantities = 1 [(buf.validate.field).map.values.int32.gt = 0];
113-
}
114-
```
115-
116-
3. **Well-known type (WKT) validation:** For the `User` message, we can add a constraint to ensure the `created_at` timestamp is in the past.
40+
## Supported Languages
11741

118-
```protobuf
119-
syntax = "proto3";
42+
This repository is the Protovalidate core: the Protobuf definition of its API and [conformance testing utilities][conformance].
12043

121-
import "google/protobuf/timestamp.proto";
122-
import "buf/validate/validate.proto";
44+
To start using Protovalidate in your projects, see the [developer quickstart][quickstart], [Protovalidate overview][protovalidate], or go directly to the repository for your language of choice:
12345

124-
message User {
125-
// User's creation date must be in the past.
126-
google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.lt_now = true];
127-
}
128-
```
46+
- [`protovalidate-go`][pv-go] (Go)
47+
- [`protovalidate-java`][pv-java] (Java)
48+
- [`protovalidate-python`][pv-python] (Python)
49+
- [`protovalidate-cc`][pv-cc] (C++)
50+
- `protovalidate-es` (TypeScript and JavaScript, coming soon!)
12951

130-
For more advanced or custom constraints, `protovalidate` allows for CEL expressions that can incorporate information across fields.
131-
132-
1. **Field-level expressions:** We can enforce that a products' `price`, sent as a string, includes a currency symbol like "$" or "£". We want to ensure that the price is positive and the currency symbol is valid.
133-
134-
```protobuf
135-
syntax = "proto3";
136-
137-
import "buf/validate/validate.proto";
138-
139-
message Product {
140-
string price = 1 [(buf.validate.field).cel = {
141-
id: "product.price",
142-
message: "Price must be positive and include a valid currency symbol ($ or £)",
143-
expression: "(this.startsWith('$') || this.startsWith('£')) && double(this.substring(1)) > 0"
144-
}];
145-
}
146-
```
147-
148-
2. **Message-level expressions:** For a `Transaction` message, we can use a message-level CEL expression to ensure that the `delivery_date` is always after the `purchase_date`.
149-
150-
```protobuf
151-
syntax = "proto3";
152-
153-
import "google/protobuf/timestamp.proto";
154-
import "buf/validate/validate.proto";
155-
156-
message Transaction {
157-
google.protobuf.Timestamp purchase_date = 1;
158-
google.protobuf.Timestamp delivery_date = 2;
159-
160-
option (buf.validate.message).cel = {
161-
id: "transaction.delivery_date",
162-
message: "Delivery date must be after purchase date",
163-
expression: "this.delivery_date > this.purchase_date"
164-
};
165-
}
166-
```
167-
168-
3. **Producing an error message in the expression:** We can produce custom error messages directly in the CEL expressions. In this example, if the `age` is less than 18, the CEL expression will evaluate to the error message string.
169-
170-
```protobuf
171-
syntax = "proto3";
172-
173-
import "buf/validate/validate.proto";
174-
175-
message User {
176-
int32 age = 1 [(buf.validate.field).cel = {
177-
id: "user.age",
178-
expression: "this < 18 ? 'User must be at least 18 years old': ''"
179-
}];
180-
}
181-
```
182-
183-
Check out [`examples`][examples] for examples on both standard constraints and custom CEL constraints.
184-
185-
### Validate Messages
186-
187-
Once the messages are annotated with constraints, use one of the [supported language libraries](#implementations) to validate; no additional code generation necessary.
52+
> [!NOTE]
53+
> Interested in adding support for another language? Check out our [Contributing Guidelines][contributing].
18854
18955
## Documentation
19056

191-
`protovalidate` provides a robust framework for validating Protobuf messages by
192-
enforcing standard and custom constraints on various data types, and offering
193-
detailed error information when validation violations occur. For a detailed
194-
overview of all its components, the supported constraints, and how to use them
195-
effectively, please refer to our [comprehensive documentation](docs/README.md).
196-
The key components include:
197-
198-
- [**Standard Constraints**](https://github.com/bufbuild/protovalidate/blob/main/docs/standard-constraints.md): `protovalidate`
199-
supports a wide range of standard
200-
constraints for all field types as well as special functionality for the
201-
Protobuf Well-Known-Types. You can apply these constraints to your Protobuf
202-
messages to ensure they meet certain common conditions.
57+
Comprehensive documentation for Protovalidate is available in [Buf's documentation library][protovalidate].
20358

204-
- [**Custom Constraints**](https://github.com/bufbuild/protovalidate/blob/main/docs/custom-constraints.md): With Google's Common
205-
Expression Language (CEL),
206-
`protovalidate` allows you to create complex, custom constraints to
207-
handle unique validation scenarios that aren't covered by the standard
208-
constraints at both the field and message level.
59+
Highlights include:
20960

210-
- [**Error Handling**](https://github.com/bufbuild/protovalidate/blob/main/docs/README.md#errors): When a violation
211-
occurs, `protovalidate` provides
212-
detailed error information to help you quickly identify the source and fix for
213-
an issue.
61+
* The [developer quickstart][quickstart]
62+
* Comprehensive RPC quickstarts for [Connect and Go][connect-go], [gRPC and Go][grpc-go], [gRPC and Java][grpc-java], and [gRPC and Python][grpc-python]
63+
* A [migration guide for protoc-gen-validate][migration-guide] users
21464

215-
### protoc-gen-validate
65+
## Contribution
21666

217-
`protovalidate` is the spiritual successor to [`protoc-gen-validate`][pgv], offering
218-
all of the same functionality present in the original plugin, without the need
219-
for custom code generation, and the new ability to describe complex constraints in CEL.
67+
We genuinely appreciate any help! If you'd like to contribute, check out these resources:
22068

221-
`protovalidate`'s constraints very closely emulate those
222-
in `protoc-gen-validate` to ensure an easy transition for developers. To
223-
migrate from `protoc-gen-validate` to `protovalidate`, use the
224-
provided [migration tool][migration-tool] to
225-
incrementally upgrade your `.proto` files.
69+
- [Contributing Guidelines][contributing]: Guidelines to make your contribution process straightforward and meaningful
70+
- [Conformance testing utilities](https://github.com/bufbuild/protovalidate/tree/main/docs/conformance.md): Utilities providing acceptance testing of `protovalidate` implementations
22671

227-
## Ecosystem
72+
## Related Sites
22873

229-
- [Buf][buf]
230-
- [CEL Specification][cel-spec]
74+
- [Buf][buf]: Enterprise-grade Kafka and gRPC for the modern age
75+
- [Common Expression Language (CEL)][cel]: The open-source technology at the core of Protovalidate
23176

23277
## Legal
23378

23479
Offered under the [Apache 2 license][license].
23580

236-
[announce]: https://buf.build/blog/protoc-gen-validate-v1-and-v2/
237-
[buf-deps]: https://buf.build/docs/configuration/v1/buf-yaml/#deps
238-
[buf-mod]: https://buf.build/bufbuild/protovalidate
23981
[buf]: https://buf.build
240-
[cel-spec]: https://github.com/google/cel-spec
241-
[ci]: https://github.com/bufbuild/protovalidate/actions/workflows/ci.yaml
242-
[conformance]: https://github.com/bufbuild/protovalidate/blob/main/docs/conformance.md
243-
[contributing]: https://github.com/bufbuild/protovalidate/blob/main/.github/CONTRIBUTING.md
244-
[docs]: https://github.com/bufbuild/protovalidate/blob/main/docs
245-
[examples]: https://github.com/bufbuild/protovalidate/tree/main/examples
246-
[file-bug]: https://github.com/bufbuild/protovalidate/issues/new?assignees=&labels=Bug&template=bug_report.md&title=%5BBUG%5D
247-
[file-feature-request]: https://github.com/bufbuild/protovalidate/issues/new?assignees=&labels=Feature&template=feature_request.md&title=%5BFeature+Request%5D
248-
[license]: https://github.com/bufbuild/protovalidate/blob/main/LICENSE
249-
[migrate]: https://buf.build/docs/migration-guides/migrate-from-protoc-gen-validate/
250-
[migration-tool]: https://github.com/bufbuild/protovalidate/blob/main/tools/protovalidate-migrate
251-
[pgv]: https://github.com/bufbuild/protoc-gen-validate
82+
[cel]: https://cel.dev
83+
25284
[pv-go]: https://github.com/bufbuild/protovalidate-go
253-
[pv-cc]: https://github.com/bufbuild/protovalidate-cc
25485
[pv-java]: https://github.com/bufbuild/protovalidate-java
25586
[pv-python]: https://github.com/bufbuild/protovalidate-python
87+
[pv-cc]: https://github.com/bufbuild/protovalidate-cc
88+
89+
[buf-mod]: https://buf.build/bufbuild/protovalidate
25690
[slack]: https://buf.build/links/slack
257-
[validate-proto]: https://buf.build/bufbuild/protovalidate/docs/main:buf.validate
91+
[license]: LICENSE
92+
[contributing]: .github/CONTRIBUTING.md
93+
94+
[protoc-gen-validate]: https://github.com/bufbuild/protoc-gen-validate
95+
[conformance]: https://github.com/bufbuild/protovalidate/blob/main/docs/conformance.md
96+
[ci]: https://github.com/bufbuild/protovalidate/actions/workflows/ci.yaml
97+
98+
[protovalidate]: https://buf.build/docs/protovalidate/
99+
[quickstart]: https://buf.build/docs/protovalidate/quickstart/
100+
[connect-go]: https://buf.build/docs/protovalidate/quickstart/connect-go/
101+
[grpc-go]: https://buf.build/docs/protovalidate/quickstart/grpc-go/
102+
[grpc-java]: https://buf.build/docs/protovalidate/quickstart/grpc-java/
103+
[grpc-python]: https://buf.build/docs/protovalidate/quickstart/grpc-python/
258104
[migration-guide]: https://buf.build/docs/migration-guides/migrate-from-protoc-gen-validate/

‎docs/README.md‎

Lines changed: 6 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,9 @@
1-
# Documentation
2-
3-
This section of the documentation is dedicated to the `protovalidate` runtime
4-
library. It serves as a comprehensive guide to help you understand and use the
5-
library effectively. Here you will find everything you need to learn about the
6-
Common Expression Language (CEL) and the constraint systems provided by the
7-
library.
8-
9-
- [CEL Overview](cel.md): This document provides an in-depth understanding of
10-
the Common Expression Language (CEL). It is an excellent starting point if you
11-
are new to CEL or need a refresher on its core concepts.
12-
13-
- [Constraints](constraints.md): This section explores the concept of
14-
constraints in `protovalidate`. You'll learn about their purpose, how they
15-
work,
16-
and how they can be applied in your project.
17-
18-
- [Custom Constraints](custom-constraints.md): This section explains how to
19-
define and apply your own custom constraints in `protovalidate`. This can
20-
be
21-
particularly useful when the standard constraints do not fit the specific
22-
requirements of your project.
23-
24-
- [Standard Constraints](standard-constraints.md): Here, you will learn
25-
about the pre-defined constraints available in the `protovalidate`
26-
library.
27-
This guide will help you understand when and how to use these standard
28-
constraints effectively.
1+
![The Buf logo](https://raw.githubusercontent.com/bufbuild/protovalidate/main/.github/buf-logo.svg)
292

30-
- [Predefined Constraints](predefined-constraints.md): This section
31-
discusses how to extend `protovalidate` with custom reusable rules that
32-
behave similarly to the standard constraints. This can be useful in order
33-
to share similar custom validation logic across multiple fields or
34-
messages.
35-
36-
- [Errors](errors.md): This section explains the error system in `protovalidate`
37-
and provides guidance on how to handle them effectively.
38-
39-
## Tools
40-
41-
The tools section introduces optional build-time convenience tools that can be
42-
used to optimize the development process with `protovalidate`. These tools are
43-
designed to help you implement new language support and assist in migrating your
44-
existing projects to `protovalidate`.
45-
46-
- [Conformance](conformance.md): This document is dedicated to explaining the
47-
Conformance tool. Learn how to use this tool to ensure all implementations
48-
align with `protovalidate`'s rules and constraints effectively.
3+
# Documentation
494

50-
- [Migrate][migrate]: If you're planning to migrate your existing project to
51-
`protovalidate`, this guide is for you. The Migrate tool is designed to help
52-
you transition smoothly, minimizing any potential disruption to your project's
53-
development.
5+
This page has moved to [Protovalidate's documentation][protovalidate] at [Buf][buf].
546

55-
[migrate]: https://buf.build/docs/migration-guides/migrate-from-protoc-gen-validate/
7+
[buf]: https://buf.build
8+
[protovalidate]: https://buf.build/docs/protovalidate/
9+
[violation-reference]: https://buf.build/docs/reference/protovalidate/violations/

0 commit comments

Comments
 (0)