Skip to content

Update documentation to describe when validators run - #2594

Closed
ruthst00 wants to merge 1 commit into
spring-projects:mainfrom
ruthst00:DATAREST-789-ruthes00
Closed

ruthst00 wants to merge 1 commit into
spring-projects:mainfrom
ruthst00:DATAREST-789-ruthes00

Conversation

@ruthst00

@ruthst00 ruthst00 commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #1161

Solution

The documentation has been updated in two files to resolve GitHub issue DATAREST-789 (#1161):

src/main/antora/modules/ROOT/pages/events.adoc — Added a new "Event Lifecycle and Object State" section that:

  • Documents step-by-step when each event fires for POST, PUT, PATCH, DELETE, and association resource operations
  • Explicitly calls out the critical PATCH behavior: BeforeSaveEvent receives the already-merged domain object (existing entity + patch applied), not the raw partial input
  • Includes a summary reference table mapping each event to its triggering HTTP method and the object state passed to the handler
  • Adds an inline comment in the annotated handler code example clarifying the PATCH object state

src/main/antora/modules/ROOT/pages/validation.adoc — Added a new "Validation Events and Object State" section that:

  • Provides a reference table mapping each event prefix (e.g., beforeSave, beforeCreate) to its HTTP trigger and the object state the validator receives
  • Adds a dedicated "Validation and PATCH Requests" subsection explicitly explaining that beforeSave validators receive the fully-merged entity for PATCH (not a partial object), with a concrete code example showing it is safe to validate all fields
  • Expands the bean name wiring section with explicit examples for both beforeCreate and beforeSave validators
  • Adds a cross-reference to the Events page for the full lifecycle details

  • You have read the Spring Data contribution guidelines.
  • You use the code formatters provided here and have them applied to your changes. Don’t submit any formatting related changes.
  • You submit test cases (unit or integration tests) that back your changes.
  • You added yourself as author in the headers of the classes you touched. Amend the date range in the Apache license header if needed. For new types, add the license header (copy from another file and set the current year only).

@spring-projects-issues spring-projects-issues added the status: waiting-for-triage An issue we've not yet triaged label Sep 6, 2026
@ruthst00 ruthst00 changed the title DATAREST-789-ruthes00. updated documentation in two files to resolve GitHub issue DATAREST-789 Updated documentation in two files to resolve GitHub issue DATAREST-789 Sep 13, 2026
@ruthst00 ruthst00 changed the title Updated documentation in two files to resolve GitHub issue DATAREST-789 Updated documentation to describe when validators run Sep 13, 2026

@mhalbritter mhalbritter left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello,

thanks for the PR. I've left some comments for your consideration.

When a `PUT` request is received to replace an existing entity:

1. The existing entity is loaded from the repository.
2. The request body is applied on top of the existing entity (non-null fields from the request body overwrite the existing entity's fields).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please verify that claim. I think PUT replaces the whole entity.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 21b3907

| Event | Triggered By | Object Passed to Handler

| `BeforeCreateEvent`
| `POST` on collection resource

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens on a PUT on a non-existent resource?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 21b3907

| New, unsaved domain object (deserialized from request body)

| `AfterCreateEvent`
| `POST` on collection resource

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens on a PUT on a non-existent resource?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 21b3907


Validators are invoked as part of the Spring Data REST event lifecycle. Understanding _when_ each validator fires and _what object_ it receives is essential for writing correct validation logic.

The following table shows the event prefix used for bean name wiring, the HTTP operation that triggers it, and the state of the object passed to the validator:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please double check that bean name wiring still works. I don't think it does.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 21b3907

[[validation.assigning-validators]]
== Assigning Validators by Bean Name

To use the bean name prefix approach, declare a `Validator` bean whose name starts with the event prefix followed by the domain type name. Spring Data REST automatically wires it to the correct event.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please double check that this still works. I don't think it does.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in previous commit

@mhalbritter mhalbritter added the status: waiting-for-feedback We need additional information before we can continue label Oct 26, 2026
@ruthst00

Copy link
Copy Markdown
Contributor Author

@mhalbritter, thanks very much for your review. I implemented your recommended changes in commit: 21b3907

@spring-projects-issues spring-projects-issues added status: feedback-provided Feedback has been provided and removed status: waiting-for-feedback We need additional information before we can continue labels Oct 27, 2026
@mhalbritter mhalbritter changed the title Updated documentation to describe when validators run Update documentation to describe when validators run Oct 30, 2026
@mhalbritter

Copy link
Copy Markdown
Contributor

Hello @ruthst00 , the 2nd commit you pushed is not signed off. Please sign it off. Thanks!

…GitHub issue DATAREST-789

Signed-off-by: ruthes00 <ruthes00@gmail.com>
@ruthst00
ruthst00 force-pushed the DATAREST-789-ruthes00 branch from 21b3907 to 8cbf92c Compare October 30, 2026 15:54
@ruthst00

Copy link
Copy Markdown
Contributor Author

@mhalbritter, I squashed the two commits and made sure the sign-off message was preserved. Thanks!

mhalbritter pushed a commit that referenced this pull request Nov 2, 2026
Closes #1161
Original Pull Request: #2594

Signed-off-by: ruthes00 <ruthes00@gmail.com>
mhalbritter added a commit that referenced this pull request Nov 2, 2026
See #1161
Original Pull Request: #2594
mhalbritter pushed a commit that referenced this pull request Nov 2, 2026
Closes #1161
Original Pull Request: #2594

Signed-off-by: ruthes00 <ruthes00@gmail.com>
mhalbritter added a commit that referenced this pull request Nov 2, 2026
See #1161
Original Pull Request: #2594
mhalbritter pushed a commit that referenced this pull request Nov 2, 2026
Closes #1161
Original Pull Request: #2594

Signed-off-by: ruthes00 <ruthes00@gmail.com>
mhalbritter added a commit that referenced this pull request Nov 2, 2026
See #1161
Original Pull Request: #2594
@mhalbritter mhalbritter added type: documentation A documentation update and removed status: waiting-for-triage An issue we've not yet triaged status: feedback-provided Feedback has been provided labels Nov 2, 2026
@mhalbritter mhalbritter added this to the 5.0.9 (2025.1.9) milestone Nov 2, 2026
@mhalbritter

Copy link
Copy Markdown
Contributor

Thanks @ruthst00 , this is merged and backported.

@mhalbritter mhalbritter closed this Nov 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: documentation A documentation update

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validator docs are silent on when validators run and implications to developers

3 participants