[Feature Request] - Document a CEL example for restricting string UUIDs to v4 or v7 #538

Feature description:

I’d like to see a documented CEL example for schemas that need string UUIDs to be limited to versions 4 or 7.

The existing generic UUID validation should keep its current meaning. This request is only for a stricter, opt-in example built on top of the existing UUID format rule.

The example would combine:

• normal UUID format validation;
• a v4 or v7 version check;
• RFC variant validation.

I’d keep the initial example limited to canonical hyphenated UUID strings.

Problem it solves or use case:

The existing UUID rule validates UUID syntax, but it intentionally does not restrict the UUID version or variant.

That’s useful as a general-purpose rule, but some APIs want a narrower contract, for example:

• externally generated IDs must be UUIDv4;
• newer identifiers may be UUIDv7;
• other UUID versions should not be accepted;
• values with the wrong RFC variant should also be rejected.

Today that requires users to work out the additional CEL expression themselves.
The existing UUID rule validates UUID syntax, but it intentionally does not restrict the UUID version or variant.

That’s useful as a general-purpose rule, but some APIs want a narrower contract, for example:

• externally generated IDs must be UUIDv4;
• newer identifiers may be UUIDv7;
• other UUID versions should not be accepted;

values with the wrong RFC variant should also be rejected.

Today that requires users to work out the additional CEL expression themselves.

A small documented example would show how to keep the generic UUID rule while layering a project-specific UUID policy on top of it, without suggesting that Protovalidate’s existing uuid behavior is incorrect.

Proposed implementation or solution:

I’d suggest documenting an example that uses the existing extension/CEL mechanism together with the normal string UUID rule.

The additional CEL predicate should accept:

• version nibble 4;
• version nibble 7;
• variant nibble 8, 9, a, or b;
• uppercase hexadecimal equivalents.

It should reject:

• UUIDs using other versions;
• a v4/v7 UUID with the wrong variant;
• Nil UUID;
• Max UUID.

The generic UUID rule should still be responsible for validating the overall UUID shape, rather than duplicating all UUID parsing logic in the additional expression.

Existing ignore semantics should continue to apply. For example, empty values should behave according to whichever ignore policy is used in the surrounding field rule.

I would not change any core rule as part of this:

• no change to uuid;
• no change to tuuid;
• no change to bytes UUID rules;
• no new core schema field.

If there is enough demand later, a reusable built-in version constraint could be discussed separately.

Contribution:

I’d be happy to help refine the CEL expression and the conformance cases for the documentation example.

I’d also be willing to help with the documentation/tests if this direction fits the project.

Examples or references:

A small set of useful conformance vectors would be:

Input - 00000000-0000-4000-8000-000000000000
Expected - Accept

Input - 00000000-0000-7000-8000-000000000000
Expected - Accept

Input - 00000000-0000-1000-8000-000000000000
Expected - Reject: version

Input - 00000000-0000-4000-c000-000000000000
Expected - Reject: variant

Input - 00000000-0000-0000-0000-000000000000
Expected - Reject: Nil UUID

Input - ffffffff-ffff-ffff-ffff-ffffffffffffReject: 
Expected - Max UUID

It would also be useful to cover:

• uppercase valid input;
• malformed UUID length/format;
• empty values under the chosen ignore policy.

If the project demonstrates CEL portability across multiple language implementations, the same vectors could be used there as well.

Additional context:

This came from looking at the current UUID rule behavior around revision d06a71c.

The existing behavior appears intentional: the generic string UUID rule validates UUID format without imposing a particular version or variant. I’m not proposing to change that contract.

The goal is just to give users a tested example for the common case where an API wants a stricter v4/v7 UUID policy while still relying on Protovalidate’s existing UUID validation.