STF-2006: Add email verification inputs to minFraud by oschwald · Pull Request #7 · maxmind/openapi

oschwald · 2026-10-09T21:08:17Z

Adds two optional inputs to the minFraud request email object: verification_time (RFC 3339 date-time) and was_verification_successful (boolean). They describe the most recent verification of the email address. The request example and the bundled spec are updated.

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Email requests can now include the time of the most recent email verification and whether it succeeded. The success field should be omitted if verification was not performed. Verification timestamps must use RFC 3339 format; timestamps before January 1, 1970, or more than two days in the future are ignored with a warning.
- Event times and phone verification times use the same RFC 3339 date-time format. The request example now shows the email verification fields.

coderabbitai · 2026-10-09T21:08:27Z

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Organization UI
Review profile: ASSERTIVE
Plan: Advanced
Run ID: d30b0563-927d-4171-820d-1e41fe7d709e

Commits

Reviewing files that changed from the base of the PR and between 90b80da and 5d23dce.

Files selected for processing: 2

bundled/minfraud.yaml
components/minfraud-request.yaml

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The minFraud request schemas add a shared RFC 3339 DateTime schema and use it for event and phone verification timestamps. The Email schema adds optional verification time and outcome fields. The request examples include values for both fields.

Changes: Email verification fields

Layer / File(s)	Summary
Define shared date-time and email verification fields `components/minfraud-request.yaml`, `bundled/minfraud.yaml`, `examples/minfraud/request.yaml`	The schemas add a shared RFC 3339 `DateTime` schema and use it for event and phone verification timestamps. The `Email` schema adds `verification_time` and `was_verification_successful`. The timestamp is ignored with a warning if it is before 1970-01-01 or more than two days in the future. The outcome field should be omitted if verification was not performed. The request examples include values for both fields.

Priority: Normal

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Feature

Merge Risk: Minimal · up to 5d23d

The change is mergeable with no actionable current risk identified.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the addition of email verification inputs, which is the main change in the pull request.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{A rabbit checks the timestamp’s place,
And marks the outcome, clear and neat.
RFC dates hop into shape,
Email fields land on nimble feet.
The sample shows what both fields hold.}

_{Comment @coderabbitai help to get the list of available commands.}

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

The email object now accepts verification_time and was_verification_successful. They describe the most recent verification of the email address. Co-Authored-By: Claude Opus 5.5 <[email protected]>

horgh

Looks good. Claude has a couple comments. I have asked it to look into the first one further and add a reply.

horgh · 2026-10-23T23:24:58Z

+      verification_time:
+        type: string
+        format: date-time
+        pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$"


A pattern next to format: date-time breaks Bean Validation in Java code that openapi-generator makes from this spec. The generator maps the field to OffsetDateTime, but it still copies the pattern into the property (DefaultCodegen.updatePropertyForString). The Java template beanValidationCore.mustache then adds @Pattern(regexp=...) to the field. Hibernate Validator supports @Pattern only on CharSequence.

Failure: a Spring user generates code from bundled/minfraud.yaml with useBeanValidation=true, which is the Spring generator default. When the user validates an Email, Hibernate Validator throws UnexpectedTypeException (HV000030: No validator could be found for constraint ... Pattern validating type java.time.OffsetDateTime).

event.time (line 116) and phone_verification_time (line 292) already have the same problem. The pattern came in with f662b29 in #6.

Suggested fix: remove the pattern from the date-time fields and rely on format: date-time. If you keep the pattern for non-Java tools, a separate PR for all three fields is fine.

🤖 Comment by Claude Opus 5.5.

Not sure this is something we should worry about.

I checked this against the openapi-generator source at v7.26.0 (the latest release). I could not run the generator here, so this is from reading the code.

What is accurate:

DefaultCodegen.updatePropertyForString maps format: date-time to a date-time property. It then copies the pattern to the property for every string format.

Both Java/beanValidationCore.mustache and JavaSpring/beanValidationCore.mustache then emit @Pattern(regexp = ...). The Spring template skips only UUIDs.

Hibernate Validator has no @Pattern validator for OffsetDateTime. It throws UnexpectedTypeException (HV000030).

What I overstated is the impact:

The java client generator has useBeanValidation=false and performBeanValidation=false by default. A customer who generates a minFraud client gets no @Pattern annotation unless they opt in.

Only the spring generator defaults to useBeanValidation=true, and it generates server stubs. Only someone who builds their own minFraud mock server would hit this.

Is anyone breaking a spec? The OpenAPI document is valid. In OpenAPI 3.1 (JSON Schema 2020-12), pattern applies to the JSON string, and format is an annotation, so the two together are well defined. Hibernate Validator follows Jakarta Validation: a constraint with no validator for the field's type raises UnexpectedTypeException.

The defect is in openapi-generator. It converts the string to OffsetDateTime and then puts a string-only constraint on the converted type. Upstream treats this as a generator bug:

UUID in Spring: fixed in Remove bean validation for uuid OpenAPITools/openapi-generator#18900, for #18095.

UUID in microprofile: still open as #19747.

date-time in Python: fixed in #24072, for #24065.

Java date-time still has the bug.

So I agree with Will: this PR does not need to change for this. If we want it fixed, the right fix is a short upstream issue for Java date-time.

🤖 Comment by Claude Opus 5.5.

I searched OpenAPITools/openapi-generator for an existing issue. I did not find one for @Pattern on a Java date-time property.

The same kind of bug (a string pattern put on a non-string Java type) is already reported for other types:

Byte arrays (Java): fixed in [Java] Update templates not to add @Pattern on byte array property OpenAPITools/openapi-generator#7153.

Enums (Java): fixed in [BUG][JAVA] Prevent generating "pattern" and "size" to ENUM OpenAPITools/openapi-generator#18658, for #18477.

UUIDs (Spring): fixed in Remove bean validation for uuid OpenAPITools/openapi-generator#18900, for #18095. That fix added the isUuid guard in JavaSpring/beanValidationCore.mustache.

UUIDs (microprofile): still open as Remove bean validation for uuid in microprofile library OpenAPITools/openapi-generator#19747.

date-time (Python): fixed in [python] Run regex pattern validators in mode="before" so they see the wire value (#24065) OpenAPITools/openapi-generator#24072, for #24065.

Two issues look related but are not:

[BUG][Spring] can't use pattern for the nullable property in request body OpenAPITools/openapi-generator#3292 is about pattern together with nullable in a Spring request body. It is a different cause with the same HV000030 error.

[BUG][JAVA]: date-time format should use pattern when provided (JavaSpring generator) OpenAPITools/openapi-generator#11853 asked Spring to use a date-time pattern as the date format. The reporter closed it with no change, and Spring still uses DateTimeFormat.ISO.DATE_TIME. So our regex cannot get into @DateTimeFormat.

A new issue would not be a duplicate. The fix would follow the UUID, enum, and byte-array fixes: skip @Pattern for isDate and isDateTime in Java/beanValidationCore.mustache and JavaSpring/beanValidationCore.mustache.

🤖 Comment by Claude Opus 5.5.

horgh · 2026-10-23T23:24:59Z

+      verification_time:
+        type: string
+        format: date-time
+        pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$"


Nit: the pattern accepts any two digits for the month and the day, so 2026-13-45T14:25:00Z matches. JSON Schema 2020-12 treats format as an annotation by default, so a validator that does not assert formats accepts this value. The web service rejects it: the value passes the regex in mmtime.ParseRFC3339, but time.Parse fails, and the response has an INPUT_INVALID warning that client-side validation did not predict.

If you keep the pattern, suggest this date part:

^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T...

It does not catch a date such as 02-30, but it closes most of the gap. event.time (line 116) and phone_verification_time (line 292) use the same pattern.

🤖 Comment by Claude Opus 5.5.

Seems optional.

horgh · 2026-10-23T23:25:00Z

+      verification_time:
+        type: string
+        format: date-time
+        pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$"


Nit: this is the third copy of the same RFC 3339 pattern. The other copies are event.time (line 116) and phone_verification_time (line 292). A change to the accepted form must go into all three places. If one copy is missed, the fields drift apart and lint does not report it.

Suggest one shared schema, for example schemas/DateTime with type, format, and pattern. Each field then uses $ref: "#/schemas/DateTime" with its own description next to it. OpenAPI 3.1 allows description next to $ref, and the Request properties (account, billing, and others) already use this form.

🤖 Comment by Claude Opus 5.5.

Might be worth it.

Reply by Claude Opus 5.5 on Greg's behalf.

Fixed in 5d23dce. A new DateTime schema holds the type, format, and pattern. event.time, email.verification_time, and phone_verification_time refer to it, and each one keeps its own description. The stricter month and day pattern is not in this change.

event.time, email.verification_time, and phone_verification_time each had a copy of the same pattern. They now refer to one DateTime schema and keep their own descriptions. Co-Authored-By: Claude Opus 5.5 <[email protected]>

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

oschwald force-pushed the greg/billing-phone-verification-inputs branch 4 times, most recently from 5f40f16 to 25b86c5 Compare October 15, 2026 22:04

Base automatically changed from greg/billing-phone-verification-inputs to main October 20, 2026 21:22

oschwald force-pushed the greg/email-verification-inputs branch from c37d74d to 2d8caaf Compare October 23, 2026 15:07

oschwald marked this pull request as ready for review October 23, 2026 15:28

Copilot AI balanced review requested due to automatic review settings October 23, 2026 15:28

Copilot AI reviewed Oct 23, 2026

oschwald force-pushed the greg/email-verification-inputs branch from 2d8caaf to 0a8c76c Compare October 23, 2026 15:53

Copilot AI balanced review requested due to automatic review settings October 23, 2026 15:53

Copilot AI reviewed Oct 23, 2026

oschwald changed the title ~~Add email verification inputs to minFraud~~ STF-2006: Add email verification inputs to minFraud Oct 23, 2026

oschwald force-pushed the greg/email-verification-inputs branch from 0a8c76c to fa4b2a1 Compare October 23, 2026 16:04

Copilot AI balanced review requested due to automatic review settings October 23, 2026 16:04

Copilot AI reviewed Oct 23, 2026

Add email verification inputs to minFraud

90b80da

The email object now accepts verification_time and was_verification_successful. They describe the most recent verification of the email address. Co-Authored-By: Claude Opus 5.5 <[email protected]>

oschwald force-pushed the greg/email-verification-inputs branch from fa4b2a1 to 90b80da Compare October 23, 2026 19:00

horgh mentioned this pull request Oct 26, 2026

STF-2006: Document email verification inputs maxmind/dev-site#1776

Merged

horgh requested changes Oct 26, 2026

View reviewed changes

Share the RFC 3339 date-time schema

5d23dce

event.time, email.verification_time, and phone_verification_time each had a copy of the same pattern. They now refer to one DateTime schema and keep their own descriptions. Co-Authored-By: Claude Opus 5.5 <[email protected]>

Copilot AI balanced review requested due to automatic review settings October 26, 2026 18:53

Copilot AI reviewed Oct 26, 2026

horgh approved these changes Oct 27, 2026

View reviewed changes

horgh merged commit 696b409 into main Oct 27, 2026
6 checks passed

horgh deleted the greg/email-verification-inputs branch October 27, 2026 15:31

Conversation

oschwald commented Oct 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

horgh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

oschwald commented Oct 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading