Skip to content

Commit

Permalink
Temporarily revert updates to the documentation in validate.proto (#327)
Browse files Browse the repository at this point in the history
  • Loading branch information
@timostamm
timostamm authored Mar 6, 2025
1 parent df9ad5c commit 0d8f50a
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 184 deletions.
138 changes: 46 additions & 92 deletions proto/protovalidate/buf/validate/validate.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3276,16 +3276,10 @@ message StringRules {
}];

// `WellKnown` rules provide advanced constraints against common string
// patterns.
// patterns
oneof well_known {
// `email` specifies that the field value must be a valid email address, for
// example "foo@example.com".
//
// Conforms to the definition for a valid email address from the [HTML standard](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address).
// Note that this standard willfully deviates from [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322),
// which allows many unexpected forms of email addresses and will easily match
// a typographical error.
//
// `email` specifies that the field value must be a valid email address
// (addr-spec only) as defined by [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1).
// If the field value isn't a valid email address, an error message will be generated.
//
// ```proto
Expand All @@ -3307,18 +3301,10 @@ message StringRules {
}
];

// `hostname` specifies that the field value must be a valid hostname, for
// example "foo.example.com".
//
// A valid hostname follows the rules below:
// - The name consists of one or more labels, separated by a dot (".").
// - Each label can be 1 to 63 alphanumeric characters.
// - A label can contain hyphens ("-"), but must not start or end with a hyphen.
// - The right-most label must not be digits only.
// - The name can have a trailing dot—for example, "foo.example.com.".
// - The name can be 253 characters at most, excluding the optional trailing dot.
//
// If the field value isn't a valid hostname, an error message will be generated.
// `hostname` specifies that the field value must be a valid
// hostname as defined by [RFC 1034](https://datatracker.ietf.org/doc/html/rfc1034#section-3.5). This constraint doesn't support
// internationalized domain names (IDNs). If the field value isn't a
// valid hostname, an error message will be generated.
//
// ```proto
// message MyString {
Expand All @@ -3339,15 +3325,8 @@ message StringRules {
}
];

// `ip` specifies that the field value must be a valid IP (v4 or v6) address.
//
// IPv4 addresses are expected in the dotted decimal format—for example, "192.168.5.21".
// IPv6 addresses are expected in their text representation—for example, "::1",
// or "2001:0DB8:ABCD:0012::0".
//
// Both formats are well-defined in the internet standard [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
// Zone identifiers for IPv6 addresses (for example, "fe80::a%en1") are supported.
//
// `ip` specifies that the field value must be a valid IP
// (v4 or v6) address, without surrounding square brackets for IPv6 addresses.
// If the field value isn't a valid IP address, an error message will be
// generated.
//
Expand All @@ -3370,9 +3349,9 @@ message StringRules {
}
];

// `ipv4` specifies that the field value must be a valid IPv4 address—for
// example "192.168.5.21". If the field value isn't a valid IPv4 address, an
// error message will be generated.
// `ipv4` specifies that the field value must be a valid IPv4
// address. If the field value isn't a valid IPv4 address, an error message
// will be generated.
//
// ```proto
// message MyString {
Expand All @@ -3393,9 +3372,9 @@ message StringRules {
}
];

// `ipv6` specifies that the field value must be a valid IPv6 address—for
// example "::1", or "d7a:115c:a1e0:ab12:4843:cd96:626b:430b". If the field
// value is not a valid IPv6 address, an error message will be generated.
// `ipv6` specifies that the field value must be a valid
// IPv6 address, without surrounding square brackets. If the field value is
// not a valid IPv6 address, an error message will be generated.
//
// ```proto
// message MyString {
Expand All @@ -3416,11 +3395,8 @@ message StringRules {
}
];

// `uri` specifies that the field value must be a valid URI, for example
// "https://example.com/foo/bar?baz=quux#frag".
//
// URI is defined in the internet standard [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
// Zone Identifiers in IPv6 address literals are supported ([RFC 6874](https://datatracker.ietf.org/doc/html/rfc6874)).
// `uri` specifies that the field value must be a valid URI as defined by
// [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
//
// If the field value isn't a valid URI, an error message will be generated.
//
Expand All @@ -3443,13 +3419,11 @@ message StringRules {
}
];

// `uri_ref` specifies that the field value must be a valid URI Reference—either
// a URI such as "https://example.com/foo/bar?baz=quux#frag", or a Relative
// Reference such as "./foo/bar?query".
// `uri_ref` specifies that the field value must be a valid URI Reference as
// defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1).
//
// URI, URI Reference, and Relative Reference are defined in the internet
// standard [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). Zone
// Identifiers in IPv6 address literals are supported ([RFC 6874](https://datatracker.ietf.org/doc/html/rfc6874)).
// A URI Reference is either a [URI](https://datatracker.ietf.org/doc/html/rfc3986#section-3),
// or a [Relative Reference](https://datatracker.ietf.org/doc/html/rfc3986#section-4.2).
//
// If the field value isn't a valid URI Reference, an error message will be
// generated.
Expand All @@ -3467,9 +3441,10 @@ message StringRules {
}];

// `address` specifies that the field value must be either a valid hostname
// (for example, "example.com"), or a valid IP (v4 or v6) address (for example,
// "192.168.0.1", or "::1"). If the field value isn't a valid hostname or IP,
// an error message will be generated.
// as defined by [RFC 1034](https://datatracker.ietf.org/doc/html/rfc1034#section-3.5)
// (which doesn't support internationalized domain names or IDNs) or a valid
// IP (v4 or v6). If the field value isn't a valid hostname or IP, an error
// message will be generated.
//
// ```proto
// message MyString {
Expand Down Expand Up @@ -3537,10 +3512,10 @@ message StringRules {
}
];

// `ip_with_prefixlen` specifies that the field value must be a valid IP
// (v4 or v6) address with prefix length—for example, "192.168.5.21/16" or
// "2001:0DB8:ABCD:0012::F1/64". If the field value isn't a valid IP with
// prefix length, an error message will be generated.
// `ip_with_prefixlen` specifies that the field value must be a valid IP (v4 or v6)
// address with prefix length. If the field value isn't a valid IP with prefix
// length, an error message will be generated.
//
//
// ```proto
// message MyString {
Expand All @@ -3562,9 +3537,9 @@ message StringRules {
];

// `ipv4_with_prefixlen` specifies that the field value must be a valid
// IPv4 address with prefix length—for example, "192.168.5.21/16". If the
// field value isn't a valid IPv4 address with prefix length, an error
// message will be generated.
// IPv4 address with prefix.
// If the field value isn't a valid IPv4 address with prefix length,
// an error message will be generated.
//
// ```proto
// message MyString {
Expand All @@ -3586,7 +3561,7 @@ message StringRules {
];

// `ipv6_with_prefixlen` specifies that the field value must be a valid
// IPv6 address with prefix length—for example, "2001:0DB8:ABCD:0012::F1/64".
// IPv6 address with prefix length.
// If the field value is not a valid IPv6 address with prefix length,
// an error message will be generated.
//
Expand All @@ -3609,15 +3584,10 @@ message StringRules {
}
];

// `ip_prefix` specifies that the field value must be a valid IP (v4 or v6)
// prefix—for example, "192.168.0.0/16" or "2001:0DB8:ABCD:0012::0/64".
//
// The prefix must have all zeros for the unmasked bits. For example,
// "2001:0DB8:ABCD:0012::0/64" designates the left-most 64 bits for the
// prefix, and the remaining 64 bits must be zero.
//
// `ip_prefix` specifies that the field value must be a valid IP (v4 or v6) prefix.
// If the field value isn't a valid IP prefix, an error message will be
// generated.
// generated. The prefix must have all zeros for the masked bits of the prefix (e.g.,
// `127.0.0.0/16`, not `127.0.0.1/16`).
//
// ```proto
// message MyString {
Expand All @@ -3639,14 +3609,9 @@ message StringRules {
];

// `ipv4_prefix` specifies that the field value must be a valid IPv4
// prefix, for example "192.168.0.0/16".
//
// The prefix must have all zeros for the unmasked bits. For example,
// "192.168.0.0/16" designates the left-most 16 bits for the prefix,
// and the remaining 16 bits must be zero.
//
// If the field value isn't a valid IPv4 prefix, an error message
// will be generated.
// prefix. If the field value isn't a valid IPv4 prefix, an error message
// will be generated. The prefix must have all zeros for the masked bits of
// the prefix (e.g., `127.0.0.0/16`, not `127.0.0.1/16`).
//
// ```proto
// message MyString {
Expand All @@ -3667,15 +3632,10 @@ message StringRules {
}
];

// `ipv6_prefix` specifies that the field value must be a valid IPv6 prefix—for
// example, "2001:0DB8:ABCD:0012::0/64".
//
// The prefix must have all zeros for the unmasked bits. For example,
// "2001:0DB8:ABCD:0012::0/64" designates the left-most 64 bits for the
// prefix, and the remaining 64 bits must be zero.
//
// `ipv6_prefix` specifies that the field value must be a valid IPv6 prefix.
// If the field value is not a valid IPv6 prefix, an error message will be
// generated.
// generated. The prefix must have all zeros for the masked bits of the prefix
// (e.g., `2001:db8::/48`, not `2001:db8::1/48`).
//
// ```proto
// message MyString {
Expand All @@ -3696,16 +3656,10 @@ message StringRules {
}
];

// `host_and_port` specifies that the field value must be valid host/port
// pair—for example, "example.com:8080".
//
// The host can be one of:
//- An IPv4 address in dotted decimal format—for example, "192.168.5.21".
//- An IPv6 address enclosed in square brackets—for example, "[2001:0DB8:ABCD:0012::F1]".
//- A hostname—for example, "example.com".
//
// The port is separated by a colon. It must be non-empty, with a decimal number
// in the range of 0-65535, inclusive.
// `host_and_port` specifies the field value must be a valid host and port
// pair. The host must be a valid hostname or IP address while the port
// must be in the range of 0-65535, inclusive. IPv6 addresses must be delimited
// with square brackets (e.g., `[::1]:1234`).
bool host_and_port = 32 [
(predefined).cel = {
id: "string.host_and_port"
Expand Down
Loading

0 comments on commit 0d8f50a

Please sign in to comment.