Protovalidate

https://protovalidate.com/
Admin
Protovalidate is a semantic validation library for Protobuf, offering standard annotations and CEL...
Tokens:92,241
Snippets:1,048
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone Example Repository

Source: https://protovalidate.com/quickstart-python

Clone the buf-examples repository to access the Protovalidate quickstart project.

```bash
$ git clone https://github.com/bufbuild/buf-examples.git
```

--------------------------------

### Install Protovalidate Go

Source: https://protovalidate.com/quickstart-go

Install Protovalidate using the go get command. Ensure you are in the correct directory within the buf-examples repository.

```bash
$ go get buf.build/go/protovalidate
```

--------------------------------

### Run the Connect Go Server

Source: https://protovalidate.com/quickstart/connect-go

Compile and start the example server on port 8080. This allows testing RPC endpoints.

```bash
$ go run cmd/server.go
```

--------------------------------

### Clone buf-examples Repository

Source: https://protovalidate.com/quickstart/grpc-python

Clone the buf-examples repository to access the Protovalidate gRPC Python quickstart code. Ensure you have Git installed.

```bash
$ git clone https://github.com/bufbuild/buf-examples.git && cd buf-examples/protovalidate/grpc-python/start
```

--------------------------------

### Setup Python environment for validation

Source: https://protovalidate.com/quickstart-python

Commands to initialize a virtual environment and install necessary dependencies for Protovalidate.

```bash
$ python3 -m venv venv
$ source ./venv/bin/activate
(venv) $ pip install -r requirements.txt --extra-index-url https://buf.build/gen/python
```

--------------------------------

### Install Protovalidate Interceptor

Source: https://protovalidate.com/quickstart/connect-go

Install the Protovalidate interceptor for Connect-Go using this go get command. This is a prerequisite for enforcing Protovalidate rules.

```bash
$ go get connectrpc.com/validate
```

--------------------------------

### Install Protovalidate Go package

Source: https://protovalidate.com/quickstart

Install the Protovalidate Go package using `go get` to enable runtime validation in your Go application.

```bash
go get buf.build/go/protovalidate
```

--------------------------------

### sint32.example

Source: https://protovalidate.com/reference/rules

Example for the example rule on sint32 fields.

```protobuf
message MySInt32 {
  sint32 value = 1 [
    (buf.validate.field).sint32.example = 1,
    (buf.validate.field).sint32.example = -10
  ];
}

```

--------------------------------

### Run Generated Java Server

Source: https://protovalidate.com/quickstart/grpc-java

Execute the generated Java code using Gradle to start the server. This command assumes a Gradle build setup for your project.

```bash
$ ./gradlew run

```

--------------------------------

### UInt64 example rule example

Source: https://protovalidate.com/reference/rules

Specifies example values (1 and 10) that the field may have. These values SHOULD conform to other rules and do not impact validation, but may be used as guidance for populating the field.

```protobuf
message MyUInt64 {
  uint64 value = 1 [
    (buf.validate.field).uint64.example = 1,
    (buf.validate.field).uint64.example = 10
  ];
}
```

--------------------------------

### Start Invoice Server

Source: https://protovalidate.com/quickstart/connect-go

The invoice server has started and is listening on localhost:8080.

```log
2025/02/03 15:30:15 INFO starting invoice server addr=localhost:8080
```

--------------------------------

### Document example values for scalar fields

Source: https://protovalidate.com/schemas/standard-rules

Documents valid example values for string, int32, and bytes fields using the `example` rule. These examples do not affect validation but help consumers understand expected values.

```protobuf
import "buf/validate/validate.proto";


message User {
  string username = 1 [
    (buf.validate.field).string.example = "alice",
    (buf.validate.field).string.example = "bob"
  ];
  int32 age = 2 [
    (buf.validate.field).int32.example = 25,
    (buf.validate.field).int32.example = 40
  ];
  bytes token = 3 [
    (buf.validate.field).bytes.example = "\x01\x02",
    (buf.validate.field).bytes.example = "\x02\x03"
  ];
}

```

--------------------------------

### SFixed64 example rule

Source: https://protovalidate.com/reference/rules

Use the `example` rule to specify values that the field may have. These values SHOULD conform to other rules. `example` values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MySFixed64 {
  sfixed64 value = 1 [
    (buf.validate.field).sfixed64.example = 1,
    (buf.validate.field).sfixed64.example = 2
  ];
}

```

--------------------------------

### sint64.example

Source: https://protovalidate.com/reference/rules

Example for the (buf.validate.field).sint64.example rule, providing example values for the field.

```protobuf
message MySInt64 {
  sint64 value = 1 [
    (buf.validate.field).sint64.example = 1,
    (buf.validate.field).sint64.example = -10
  ];
}

```

--------------------------------

### Duration field with `example` values

Source: https://protovalidate.com/reference/rules

Use `example` to specify example values for the field. These values do not affect validation but may serve as guidance for populating the field.

```protobuf
message MyDuration {
  google.protobuf.Duration value = 1 [
    (buf.validate.field).duration.example = { seconds: 1 },
    (buf.validate.field).duration.example = { seconds: 2 }
  ];
}
```

--------------------------------

### Clone the example repository

Source: https://protovalidate.com/quickstart/grpc-go

Initializes the project environment by cloning the buf-examples repository.

```bash
$ git clone https://github.com/bufbuild/buf-examples.git && cd buf-examples/protovalidate/grpc-go/start
```

--------------------------------

### Start gRPC Server

Source: https://protovalidate.com/quickstart/grpc-python

Run the invoice server to test its functionality. The server will start on port 50051.

```bash
(.venv) $ python invoice_server.py
```

--------------------------------

### Start the server

Source: https://protovalidate.com/quickstart/grpc-go

Compiles and runs the gRPC server.

```bash
$ go run cmd/server.go
```

--------------------------------

### Document enum example values

Source: https://protovalidate.com/schemas/standard-rules

Use `example` to document valid enum values. These examples do not affect validation but help consumers understand expected values.

```proto
import "buf/validate/validate.proto";


enum Priority {
  PRIORITY_UNSPECIFIED = 0;
  PRIORITY_LOW = 1;
  PRIORITY_MEDIUM = 2;
  PRIORITY_HIGH = 3;
  PRIORITY_CRITICAL = 4;
}


message Request {
  // Only allow low, medium, or high priority and provide an example.
  Priority priority = 1 [
    (buf.validate.field).enum = { in: [1, 2, 3] },
    (buf.validate.field).enum.example = 1,  // PRIORITY_LOW
    (buf.validate.field).enum.example = 2   // PRIORITY_MEDIUM
  ];
}

```

--------------------------------

### Clone Example Repository

Source: https://protovalidate.com/quickstart-go

Clone the buf-examples repository to access starter projects for Protovalidate.

```bash
$ git clone https://github.com/bufbuild/buf-examples.git
```

--------------------------------

### int32.example rule example

Source: https://protovalidate.com/reference/rules

Use the example rule to specify values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MyInt32 {
  int32 value = 1 [
    (buf.validate.field).int32.example = 1,
    (buf.validate.field).int32.example = -10
  ];
}

```

--------------------------------

### Timestamp example rule example

Source: https://protovalidate.com/reference/rules

Use `(buf.validate.field).timestamp.example` to specify example values for a Timestamp field. These values do not affect validation but provide guidance for populating the field.

```protobuf
message MyTimestamp {
  google.protobuf.Timestamp value = 1 [
    (buf.validate.field).timestamp.example = { seconds: 1672444800 },
    (buf.validate.field).timestamp.example = { seconds: 1672531200 }
  ];
}

```

--------------------------------

### uint32.example rule example

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MyUInt32 {
  uint32 value = 1 [
    (buf.validate.field).uint32.example = 1,
    (buf.validate.field).uint32.example = 10
  ];
}
```

--------------------------------

### sint32.lt

Source: https://protovalidate.com/reference/rules

Example for the lt rule on sint32 fields.

```protobuf
message MySInt32 {
  // must be less than 10
  sint32 value = 1 [(buf.validate.field).sint32.lt = 10];
}

```

--------------------------------

### Double example rule example

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. example values do not impact validation but may be used as helpful guidance on how to populate the field.

```protobuf
message MyDouble {
  double value = 1 [
    (buf.validate.field).double.example = 1.0,
    (buf.validate.field).double.example = inf
  ];
}
```

--------------------------------

### int64.example rule example

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MyInt64 {
  int64 value = 1 [
    (buf.validate.field).int64.example = 1,
    (buf.validate.field).int64.example = -10
  ];
}
```

--------------------------------

### Provide example values for string field using string.example

Source: https://protovalidate.com/reference/rules

Use this constraint to specify example values that the field may have. These values SHOULD conform to other rules and do not impact validation, but may be used as helpful guidance on how to populate the field.

```protobuf
message MyString {
  string value = 1 [
    (buf.validate.field).string.example = "hello",
    (buf.validate.field).string.example = "world"
  ];
}

```

--------------------------------

### FieldMask example rule example

Source: https://protovalidate.com/reference/rules

The example rule specifies values that the field may have. These values SHOULD conform to other rules and do not impact validation, but may be used as guidance for populating the field. The example shows two example values for a FieldMask field.

```protobuf
message MyFieldMask {
  google.protobuf.FieldMask value = 1 [
    (buf.validate.field).field_mask.example = { paths: ["a", "b"] },
    (buf.validate.field).field_mask.example = { paths: ["c.a", "d"] }
  ];
}
```

--------------------------------

### fixed64.example example

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. example values do not impact validation but may be used as guidance for populating the field.

```protobuf
message MyFixed64 {
  fixed64 value = 1 [
    (buf.validate.field).fixed64.example = 1,
    (buf.validate.field).fixed64.example = 2
  ];
}
```

--------------------------------

### (buf.validate.field).sint64.example

Source: https://protovalidate.com/reference/rules

The `example` rule for sint64 fields provides example values that do not affect validation but serve as guidance.

```APIDOC
## (buf.validate.field).sint64.example

### Description
`example` specifies values that the field may have. These values SHOULD conform to other rules. `example` values will not impact validation but may be used as helpful guidance on how to populate the given field.

### Field Option
- **example** (repeated sint64) - Optional - Example values for the field.

### Example
```protobuf
message MySInt64 {
  sint64 value = 1 [
    (buf.validate.field).sint64.example = 1,
    (buf.validate.field).sint64.example = -10
  ];
}
```
```

--------------------------------

### sint32.in

Source: https://protovalidate.com/reference/rules

Example for the in rule on sint32 fields.

```protobuf
message MySInt32 {
  // must be in list [1, 2, 3]
  sint32 value = 1 [(buf.validate.field).sint32 = { in: [1, 2, 3] }];
}

```

--------------------------------

### fixed32.example rule example

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MyFixed32 {
  fixed32 value = 1 [
    (buf.validate.field).fixed32.example = 1,
    (buf.validate.field).fixed32.example = 2
  ];
}

```

--------------------------------

### float.example rule example

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MyFloat {
  float value = 1 [
    (buf.validate.field).float.example = 1.0,
    (buf.validate.field).float.example = inf
  ];
}
```

--------------------------------

### (buf.validate.field).sint32.example

Source: https://protovalidate.com/reference/rules

The `example` rule for sint32 fields provides example values that do not affect validation but serve as guidance.

```APIDOC
## (buf.validate.field).sint32.example

### Description
`example` specifies values that the field may have. These values SHOULD conform to other rules. `example` values will not impact validation but may be used as helpful guidance on how to populate the given field.

### Field Option
- **Option**: `(buf.validate.field).sint32.example`
- **Type**: sint32 (repeatable)
- **Usage**: Set the field option multiple times to provide example values.

### Example
```proto
message MySInt32 {
  sint32 value = 1 [
    (buf.validate.field).sint32.example = 1,
    (buf.validate.field).sint32.example = -10
  ];
}
```
```

--------------------------------

### sint32.gte

Source: https://protovalidate.com/reference/rules

Examples for the gte rule and its interaction with lt.

```protobuf
message MySInt32 {
 // must be greater than or equal to 5 [sint32.gte]
 sint32 value = 1 [(buf.validate.field).sint32.gte = 5];


 // must be greater than or equal to 5 and less than 10 [sint32.gte_lt]
 sint32 other_value = 2 [(buf.validate.field).sint32 = { gte: 5, lt: 10 }];


 // must be greater than or equal to 10 or less than 5 [sint32.gte_lt_exclusive]
 sint32 another_value = 3 [(buf.validate.field).sint32 = { gte: 10, lt: 5 }];
}

```

--------------------------------

### Successful Test Output Example

Source: https://protovalidate.com/quickstart/connect-go

Example of the output when all Go tests pass, indicating successful validation and execution of test cases. It shows the overall test status and individual test case results.

```text
---
PASS: TestCreateInvoice (0.00s)
    --- PASS: TestCreateInvoice/InvoiceId_is_required (0.01s)
    --- PASS: TestCreateInvoice/InvoiceId_must_be_a_UUID (0.00s)
    --- PASS: TestCreateInvoice/Two_line_items_cannot_have_the_same_identifier (0.01s)
PASS
ok      github.com/bufbuild/buf-examples/protovalidate/connect-go/finish/internal/invoice       0.485s

```

--------------------------------

### sint32.lte

Source: https://protovalidate.com/reference/rules

Examples for the lte rule and its interaction with gt and lt.

```protobuf
message MySInt32 {
  // must be greater than 5 [sint32.gt]
  sint32 value = 1 [(buf.validate.field).sint32.gt = 5];


  // must be greater than 5 and less than 10 [sint32.gt_lt]
  sint32 other_value = 2 [(buf.validate.field).sint32 = { gt: 5, lt: 10 }];


  // must be greater than 10 or less than 5 [sint32.gt_lt_exclusive]
  sint32 another_value = 3 [(buf.validate.field).sint32 = { gt: 10, lt: 5 }];
}

```

--------------------------------

### Install Protovalidate Middleware

Source: https://protovalidate.com/quickstart/grpc-go

Command to fetch the required Go gRPC middleware dependency.

```bash
$ go get github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/protovalidate@v2.3.2
```

--------------------------------

### sint64.gt

Source: https://protovalidate.com/reference/rules

Examples for the (buf.validate.field).sint64.gt rule and its combinations with lt and lte.

```protobuf
message MySInt64 {
  // must be greater than 5 [sint64.gt]
  sint64 value = 1 [(buf.validate.field).sint64.gt = 5];


  // must be greater than 5 and less than 10 [sint64.gt_lt]
  sint64 other_value = 2 [(buf.validate.field).sint64 = { gt: 5, lt: 10 }];


  // must be greater than 10 or less than 5 [sint64.gt_lt_exclusive]
  sint64 another_value = 3 [(buf.validate.field).sint64 = { gt: 10, lt: 5 }];
}

```

--------------------------------

### sint64.gte

Source: https://protovalidate.com/reference/rules

Examples for the (buf.validate.field).sint64.gte rule and its combinations with lt and lte.

```protobuf
message MySInt64 {
  // must be greater than or equal to 5 [sint64.gte]
  sint64 value = 1 [(buf.validate.field).sint64.gte = 5];


  // must be greater than or equal to 5 and less than 10 [sint64.gte_lt]
  sint64 other_value = 2 [(buf.validate.field).sint64 = { gte: 5, lt: 10 }];


  // must be greater than or equal to 10 or less than 5 [sint64.gte_lt_exclusive]
  sint64 another_value = 3 [(buf.validate.field).sint64 = { gte: 10, lt: 5 }];
}

```

--------------------------------

### Run the gRPC Server

Source: https://protovalidate.com/quickstart/grpc-java

Compile and run the gRPC server using its Gradle wrapper. The server will start on port 50051.

```bash
$ ./gradlew run
```

--------------------------------

### Install Protovalidate dependency

Source: https://protovalidate.com/quickstart/grpc-go

Adds the Protovalidate Go module to the project.

```bash
$ go get buf.build/go/protovalidate
```

--------------------------------

### CEL bytes.startsWith

Source: https://protovalidate.com/reference/cel_extensions

Checks if a bytes sequence starts with the specified prefix.

```APIDOC
## bytes.startsWith

### Description
Overload of the CEL standard `startsWith` to support bytes types.

### Signature
`bytes.startsWith(bytes) -> bool`
```

--------------------------------

### Test Execution Results

Source: https://protovalidate.com/quickstart/grpc-java

Example output showing successful test runs for various Protovalidate scenarios.

```text
InvoiceServerTest > InvoiceId is required PASSED

InvoiceServerTest > Two line items cannot have the same product_id and unit price PASSED

InvoiceServerTest > A valid invoice passes validation PASSED
```

--------------------------------

### Clone buf-examples Repository

Source: https://protovalidate.com/quickstart/connect-go

Clone the buf-examples repository and navigate to the protovalidate/connect-go/start directory to begin.

```bash
$ git clone https://github.com/bufbuild/buf-examples.git && cd buf-examples/protovalidate/connect-go/start
```

--------------------------------

### Type conversion in CEL

Source: https://protovalidate.com/schemas/custom-rules

Example demonstrating type conversion in CEL expressions for field validation.

```protobuf
import "buf/validate/validate.proto";


message Sound {
  uint32 frequency_hz = 1 [(buf.validate.field).cel = {
    id: "frequency_in_the_audible_range"
    expression:
      "this < 20 ? string(this) + ' hz is too low for human ears'"
      ": this > 20000 ? string(this) + ' hz is too high for human ears'"
      ": ''"
  }];
}

```

--------------------------------

### sint64.lt

Source: https://protovalidate.com/reference/rules

Example for the (buf.validate.field).sint64.lt rule, requiring the field value to be less than 10.

```protobuf
message MySInt64 {
  // must be less than 10
  sint64 value = 1 [(buf.validate.field).sint64.lt = 10];
}

```

--------------------------------

### Set Up Python Virtual Environment

Source: https://protovalidate.com/quickstart/grpc-python

Create and activate a Python virtual environment, then install project dependencies including Protovalidate. Requires Python 3.9+ and pip.

```bash
$ python3 -m venv .venv
$ source .venv/bin/activate
(venv) $ pip install -r requirements.txt --extra-index-url https://buf.build/gen/python
```

--------------------------------

### Server startup log

Source: https://protovalidate.com/quickstart/grpc-go

Expected output upon successful server initialization.

```text
2025/02/04 19:52:02 INFO starting invoice service address=:50051
```

--------------------------------

### Timestamp subtraction with now

Source: https://protovalidate.com/schemas/custom-rules

Subtracts two timestamps to produce a duration and uses `now` to get the current timestamp. Validates that the start time is at least 24 hours ahead.

```proto
import "buf/validate/validate.proto";


message BookReservationRequest {
  google.protobuf.Timestamp start_time = 1 [(buf.validate.field).cel = {
    id: "book_24_hrs_ahead"
    message: "must book at least 24 hours ahead"
    expression: "duration('24h') <= this - now"
  }];
}

```

--------------------------------

### Validate Protobuf Message in Go

Source: https://protovalidate.com/quickstart-go

Use the Protovalidate Go package to validate a Protobuf message. Ensure the Protovalidate library is installed via 'go get'.

```go
err := protovalidate.Validate(message)
```

--------------------------------

### Clone buf-examples Repository

Source: https://protovalidate.com/quickstart/grpc-java

Clone the buf-examples repository and navigate to the protovalidate/grpc-java/start directory to begin.

```bash
$ git clone https://github.com/bufbuild/buf-examples.git && cd buf-examples/protovalidate/grpc-java/start
```

--------------------------------

### Validate byte prefix and suffix with `.startsWith()` and `.endsWith()`

Source: https://protovalidate.com/schemas/custom-rules

Uses `.startsWith()` and `.endsWith()` to check for byte sequence prefixes and suffixes. The example validates that script files start with a shebang (`#!`) and end with a newline (`\x0A`).

```protobuf
import "buf/validate/validate.proto";


message ScriptFile {
  bytes content = 1 [(buf.validate.field).cel = {
    id: "script_start_with_shebang_end_with_line_feed"
    expression:
      "!this.startsWith(bytes('#!')) ? 'must start with #!'"
      ": !this.endsWith(bytes('\\x0A')) ? 'must end with a new line'"
      ": ''"
  }];
}

```

--------------------------------

### Server Startup Output

Source: https://protovalidate.com/quickstart/grpc-go

Expected console output upon successful server initialization.

```text
2025/02/05 06:51:44 INFO starting invoice service address=:50051
```

```text
2025/02/03 15:30:15 INFO starting invoice server addr=localhost:8080
```

--------------------------------

### Compile Protobuf and Run Server

Source: https://protovalidate.com/quickstart/grpc-go

Commands to regenerate Protobuf code and execute the Go server.

```bash
$ buf generate
```

```bash
$ go run cmd/server.go
```

--------------------------------

### Install Protovalidate Dependency

Source: https://protovalidate.com/quickstart-es

Install the Protovalidate npm package in your project to enable message validation.

```bash
$ npm install @bufbuild/protovalidate

```

--------------------------------

### Run the migration tool

Source: https://protovalidate.com/migration-guides/migrate-from-protoc-gen-validate

Executes the migration tool to add Protovalidate annotations alongside existing ones.

```bash
$ go run ./tools/protovalidate-migrate -w /path/to/protos
```

--------------------------------

### Invalid User Data Example

Source: https://protovalidate.com/about

An example of data that is valid according to Protobuf types but semantically incorrect.

```json
{"id": "", "email": "not-an-email", "name": "", "age": -5}

```

--------------------------------

### Install Protovalidate Dependency

Source: https://protovalidate.com/quickstart/grpc-python

Use pip to install the protovalidate package within your Python virtual environment.

```bash
(.venv) $ pip install protovalidate
```

--------------------------------

### Timestamp lt rule example

Source: https://protovalidate.com/reference/rules

Requires the timestamp field value to be less than the specified value. The example sets seconds to 1672444800, which corresponds to 2023-01-01T00:00:00Z.

```protobuf
message MyTimestamp {
  // timestamp must be less than '2023-01-01T00:00:00Z' [timestamp.lt]
  google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.lt = { seconds: 1672444800 }];
}

```

--------------------------------

### Timestamp const rule example

Source: https://protovalidate.com/reference/rules

Requires the timestamp field to exactly match the specified value. The example sets seconds to 1727998800, which corresponds to 2023-05-03T10:00:00Z.

```protobuf
message MyTimestamp {
  // value must equal 2023-05-03T10:00:00Z
  google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.const = {seconds: 1727998800}];
}

```

--------------------------------

### Timestamp lte rule example

Source: https://protovalidate.com/reference/rules

Requires the timestamp field value to be less than or equal to the specified value. The example sets seconds to 1678867200, which corresponds to 2023-05-14T00:00:00Z.

```protobuf
message MyTimestamp {
  // timestamp must be less than or equal to '2023-05-14T00:00:00Z' [timestamp.lte]
  google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.lte = { seconds: 1678867200 }];
}

```

--------------------------------

### Compile Protobuf and Go

Source: https://protovalidate.com/quickstart/connect-go

Run this command to compile your Protobuf files and regenerate Go code. Ensure your server is stopped before compiling.

```bash
$ buf generate
```

--------------------------------

### Clone the protovalidate repository

Source: https://protovalidate.com/migration-guides/migrate-from-protoc-gen-validate

Initial step to obtain the migration tool source code.

```bash
$ git clone https://github.com/bufbuild/protovalidate.git && cd protovalidate
```

--------------------------------

### Timestamp within rule example

Source: https://protovalidate.com/reference/rules

Use `(buf.validate.field).timestamp.within` to require a Timestamp field to be within a specified duration of the current time. The example sets a 1-hour window using `seconds: 3600`.

```protobuf
message MyTimestamp {
  // must be within 1 hour of now
  google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.within = {seconds: 3600}];
}

```

--------------------------------

### Timestamp gt rule examples

Source: https://protovalidate.com/reference/rules

Requires the timestamp field value to be greater than the specified value. The example also shows combined gt and lt rules, and a reversed range where the field must be outside the specified range.

```protobuf
message MyTimestamp {
  // timestamp must be greater than '2023-01-01T00:00:00Z' [timestamp.gt]
  google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.gt = { seconds: 1672444800 }];


  // timestamp must be greater than '2023-01-01T00:00:00Z' and less than '2023-01-02T00:00:00Z' [timestamp.gt_lt]
  google.protobuf.Timestamp another_value = 2 [(buf.validate.field).timestamp = { gt: { seconds: 1672444800 }, lt: { seconds: 1672531200 } }];


  // timestamp must be greater than '2023-01-02T00:00:00Z' or less than '2023-01-01T00:00:00Z' [timestamp.gt_lt_exclusive]
  google.protobuf.Timestamp other_value = 3 [(buf.validate.field).timestamp = { gt: { seconds: 1672531200 }, lt: { seconds: 1672444800 } }];
}

```

--------------------------------

### Set bool.example to specify allowed boolean values

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. `example` values will not impact validation but may be used as helpful guidance on how to populate the given field.

```protobuf
message MyBool {
  bool value = 1 [
    (buf.validate.field).bool.example = true,
    (buf.validate.field).bool.example = false
  ];
}

```

--------------------------------

### FieldMask in rule example

Source: https://protovalidate.com/reference/rules

The in rule requires the field value to only contain paths matching specified values or their subpaths. If any path doesn't match, an error is generated. The example shows a FieldMask that must only contain paths listed in `in`.

```protobuf
message MyFieldMask {
  //  The `value` FieldMask must only contain paths listed in `in`.
  google.protobuf.FieldMask value = 1 [(buf.validate.field).field_mask = {
      in: ["a", "b", "c.a"]
  }];
}
```

--------------------------------

### Initialize and Use Protovalidate Validator

Source: https://protovalidate.com/quickstart-es

Demonstrates how to create a Protovalidate validator instance and use it to validate a message against a schema.

```javascript
const validator = createValidator();
const result = validator.validate(Schema, message);
```

--------------------------------

### Import Connect and Validate Packages

Source: https://protovalidate.com/quickstart/connect-go

Import the necessary Connect and Protovalidate packages in your cmd/server.go file. These imports are required to use the Protovalidate interceptor.

```go
import (
  "log/slog"
  "net/http"
  "os"
  "time"


  "connectrpc.com/connect"
  "connectrpc.com/validate"
  "github.com/bufbuild/buf-examples/protovalidate/connect-go/finish/gen/invoice/v1/invoicev1connect"
  "github.com/bufbuild/buf-examples/protovalidate/connect-go/finish/internal/invoice"
  "golang.org/x/net/http2"
  "golang.org/x/net/http2/h2c"
)
```

--------------------------------

### fixed64.gt examples

Source: https://protovalidate.com/reference/rules

Requires the field value to be greater than the specified value (exclusive). If gt is larger than a specified lt or lte, the range is reversed and the field must be outside the range. Includes examples for gt, gt_lt, and gt_lt_exclusive.

```protobuf
message MyFixed64 {
  // must be greater than 5 [fixed64.gt]
  fixed64 value = 1 [(buf.validate.field).fixed64.gt = 5];


  // must be greater than 5 and less than 10 [fixed64.gt_lt]
  fixed64 other_value = 2 [(buf.validate.field).fixed64 = { gt: 5, lt: 10 }];


  // must be greater than 10 or less than 5 [fixed64.gt_lt_exclusive]
  fixed64 another_value = 3 [(buf.validate.field).fixed64 = { gt: 10, lt: 5 }];
}
```

--------------------------------

### General migration tool usage

Source: https://protovalidate.com/migration-guides/migrate-from-protoc-gen-validate

Standard command structure for the migration tool.

```bash
$ go run ./tools/protovalidate-migrate <flags> /path/to/proto
```

--------------------------------

### Timestamp gte rule examples

Source: https://protovalidate.com/reference/rules

Requires the timestamp field value to be greater than or equal to the specified value. The example also shows combined gte and lt rules, and a reversed range where the field must be outside the specified range.

```protobuf
message MyTimestamp {
  // timestamp must be greater than or equal to '2023-01-01T00:00:00Z' [timestamp.gte]
  google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.gte = { seconds: 1672444800 }];


  // timestamp must be greater than or equal to '2023-01-01T00:00:00Z' and less than '2023-01-02T00:00:00Z' [timestamp.gte_lt]
  google.protobuf.Timestamp another_value = 2 [(buf.validate.field).timestamp = { gte: { seconds: 1672444800 }, lt: { seconds: 1672531200 } }];


  // timestamp must be greater than or equal to '2023-01-02T00:00:00Z' or less than '2023-01-01T00:00:00Z' [timestamp.gte_lt_exclusive]
  google.protobuf.Timestamp other_value = 3 [(buf.validate.field).timestamp = { gte: { seconds: 1672531200 }, lt: { seconds: 1672444800 } }];
}

```

--------------------------------

### fixed64.gte examples

Source: https://protovalidate.com/reference/rules

Requires the field value to be greater than or equal to the specified value (exclusive). If gte is larger than a specified lt or lte, the range is reversed and the field must be outside the range. Includes examples for gte, gte_lt, and gte_lt_exclusive.

```protobuf
message MyFixed64 {
  // must be greater than or equal to 5 [fixed64.gte]
  fixed64 value = 1 [(buf.validate.field).fixed64.gte = 5];


  // must be greater than or equal to 5 and less than 10 [fixed64.gte_lt]
  fixed64 other_value = 2 [(buf.validate.field).fixed64 = { gte: 5, lt: 10 }];


  // must be greater than or equal to 10 or less than 5 [fixed64.gte_lt_exclusive]
  fixed64 another_value = 3 [(buf.validate.field).fixed64 = { gte: 10, lt: 5 }];
}
```

--------------------------------

### FieldMask not_in rule example

Source: https://protovalidate.com/reference/rules

The not_in rule requires the field value to not contain paths matching specified values or their subpaths. If any path matches, an error is generated. The example shows a FieldMask that shall not contain paths listed in `not_in`.

```protobuf
message MyFieldMask {
  //  The `value` FieldMask shall not contain paths listed in `not_in`.
  google.protobuf.FieldMask value = 1 [(buf.validate.field).field_mask = {
      not_in: ["forbidden", "immutable", "c.a"]
  }];
}
```

--------------------------------

### FieldMask const rule example

Source: https://protovalidate.com/reference/rules

The const rule requires the field to match the specified FieldMask exactly. If the field's value deviates, an error is generated. The example shows a message with a FieldMask field that must equal ["a"].

```protobuf
message MyFieldMask {
  // value must equal ["a"]
  google.protobuf.FieldMask value = 1 [(buf.validate.field).field_mask.const = {
      paths: ["a"]
  }];
}
```

--------------------------------

### sint32.not_in

Source: https://protovalidate.com/reference/rules

Example for the not_in rule on sint32 fields.

```protobuf
message MySInt32 {
  // value must not be in list [1, 2, 3]
  sint32 value = 1 [(buf.validate.field).sint32 = { not_in: [1, 2, 3] }];
}

```

--------------------------------

### Implement table-driven tests for Protovalidate

Source: https://protovalidate.com/quickstart/grpc-go

Example of a test case map that defines input producers and expected violations for invoice creation.

```go
func TestCreateInvoice(t *testing.T) {
  // Code omitted for brevity...


  testCases := map[string]struct {
    producer          func(invoice *invoicev1.Invoice) *invoicev1.Invoice
    violations []violationSpec
  }{
    "An invoice can be created": {
      producer: func(invoice *invoicev1.Invoice) *invoicev1.Invoice {
        return invoice
      },
    },
    "InvoiceId is required": {
      producer: func(invoice *invoicev1.Invoice) *invoicev1.Invoice {
        invoice.InvoiceId = ""
        return invoice
      },
      violations: []violationSpec{
        {
          ruleID:    "string.uuid_empty",
          fieldPath: "invoice.invoice_id",
          message:   "value is empty, which is not a valid UUID",
        },
      },
    },
    "Two line items cannot have the same product_id and unit price": {
      producer: func(invoice *invoicev1.Invoice) *invoicev1.Invoice {
        invoice.GetLineItems()[0].ProductId = invoice.GetLineItems()[1].GetProductId()
        invoice.GetLineItems()[0].UnitPrice = invoice.GetLineItems()[1].GetUnitPrice()
        return invoice
      },
      violations: []violationSpec{
        {
          ruleID:    "line_items.logically_unique",
          fieldPath: "invoice.line_items",
          message:   "line items must be unique combinations of product_id and unit_price",
        },
      },
    },
  }
  // Code omitted for brevity
}
```

--------------------------------

### sint32.const

Source: https://protovalidate.com/reference/rules

Example for the const rule on sint32 fields.

```protobuf
message MySInt32 {
  // value must equal 42
  sint32 value = 1 [(buf.validate.field).sint32.const = 42];
}

```

--------------------------------

### Run Go Tests

Source: https://protovalidate.com/quickstart/connect-go

Execute Go tests to verify the current state of validation logic. Initially, some tests are expected to fail.

```bash
$ go test -v ./...
--- PASS: TestCreateInvoice/A_valid_invoice_passes_validation (0.00s)
--- FAIL: TestCreateInvoice/InvoiceId_is_required (0.00s)
--- FAIL: TestCreateInvoice/Two_line_items_cannot_have_the_same_product_id_and_unit_price (0.00s)
```

--------------------------------

### Apply (buf.validate.field).bytes.example rule

Source: https://protovalidate.com/reference/rules

Specifies values that the field may have. These values SHOULD conform to other rules. Example values do not impact validation but may be used as helpful guidance on how to populate the field.

```protobuf
message MyBytes {
  bytes value = 1 [
    (buf.validate.field).bytes.example = "\x01\x02",
    (buf.validate.field).bytes.example = "\x02\x03"
  ];
}

```

--------------------------------

### Build Protobuf Module with Buf

Source: https://protovalidate.com/quickstart-python

Run 'buf build' to compile your Protobuf schemas after adding Protovalidate as a dependency and defining validation rules.

```bash
$ buf build
```

--------------------------------

### Double gt rule examples

Source: https://protovalidate.com/reference/rules

Requires the field value to be greater than the specified value (exclusive). If gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. The example shows gt alone, gt with lt, and gt with lt reversed.

```protobuf
message MyDouble {
  // must be greater than 5.0 [double.gt]
  double value = 1 [(buf.validate.field).double.gt = 5.0];


  // must be greater than 5 and less than 10.0 [double.gt_lt]
  double other_value = 2 [(buf.validate.field).double = { gt: 5.0, lt: 10.0 }];


  // must be greater than 10 or less than 5.0 [double.gt_lt_exclusive]
  double another_value = 3 [(buf.validate.field).double = { gt: 10.0, lt: 5.0 }];
}
```

--------------------------------

### Run buf generate

Source: https://protovalidate.com/quickstart-go

Execute the `buf generate` command to incorporate your new rules and configurations into the generated code.

```bash
$ buf generate

```

--------------------------------

### Run Gradle Tests

Source: https://protovalidate.com/quickstart/grpc-java

Execute all defined tests using Gradle to verify Protovalidate configurations and error handling.

```bash
$ ./gradlew test --rerun
```

--------------------------------

### UInt64 gt rule examples (gt, gt_lt, gt_lt_exclusive)

Source: https://protovalidate.com/reference/rules

Requires the field value to be greater than the specified value. When combined with lt/lte, if gt is larger than the upper bound, the range is reversed and the value must be outside the range. Three examples show gt alone, gt with lt, and reversed range.

```protobuf
message MyUInt64 {
  // must be greater than 5 [uint64.gt]
  uint64 value = 1 [(buf.validate.field).uint64.gt = 5];


  // must be greater than 5 and less than 10 [uint64.gt_lt]
  uint64 other_value = 2 [(buf.validate.field).uint64 = { gt: 5, lt: 10 }];


  // must be greater than 10 or less than 5 [uint64.gt_lt_exclusive]
  uint64 another_value = 3 [(buf.validate.field).uint64 = { gt: 10, lt: 5 }];
}
```

--------------------------------

### Test Execution Results

Source: https://protovalidate.com/quickstart/grpc-python

Example output showing successful execution of Protovalidate unit tests. 'ok' indicates that each test passed as expected.

```text
test_a_valid_invoice_can_be_created (invoice_server_test.InvoiceServerTest) ... ok
test_invoice_id_must_be_a_uuid (invoice_server_test.InvoiceServerTest) ... ok
test_two_line_items_cannot_have_the_same_product_id_and_unit_price (invoice_server_test.InvoiceServerTest) ... ok

```
Tokens:
Raw