feature: Add support for showing changelog for deprecated properties by jainsachi88 · Pull Request #782 · oasdiff/oasdiff

jainsachi88 · 2026-01-23T17:23:24Z

Add support for detecting deprecated request and response properties in changelogs

Detect when properties in request/response bodies become deprecated, with sunset date validation. This feature also support nested properties, allOf/oneOf/anyOf schemas, and prevent duplicate reports for the same property.

Changes:

New files added
Add function that supports request property deprecation with sunset validation checker/check_request_property_deprecation.go
checker/check_request_property_deprecation_test.go
Add function that supports response property deprecation with sunset validation
checker/check_response_property_deprecation.go
checker/check_response_property_deprecation_test.go
Also some sample files created in data/deprecation
Updated files
Messages updated for oasdiff CLI in checker/localizations_src/en/messages.yaml
Update localization messages to work with new comment-based approach
Updated BackwardCompatibilityRules in checker/rules.go

Example outputs:

Without details: "request-property-deprecated"
With sunset: "request-property-deprecated with sunset date(2026-12-31)"
With Inavalid/Missing sunset: "request-property-deprecated without/missing sunset date"

reuvenharrison · 2026-01-24T11:40:56Z

checker/check_request_property_deprecation.go

+			// Track reported properties to avoid duplicates per operation
+			reportedProperties := make(map[string]bool)
+


This is a pragmatic solution to the duplicate reporting issue. While #594 outlines a more comprehensive approach with media-type context, this provides immediate user value with low risk.

The deduplication logic is isolated and easy to maintain. When the wider solution from #594 is implemented, this can be cleanly removed without affecting other code.

Suggestion: Consider adding a TODO comment to document the temporary nature:

// TODO(#594): Remove this deduplication when media-type context is added to messages reportedProperties := make(map[string]bool)

reuvenharrison · 2026-01-24T11:48:42Z

Some tasks remain before we can merge:

Fix failing tests
Check messages for extra args (example below)

❯ oasdiff changelog data/deprecation/request_property_deprecation_base.yaml data/deprecation/request_property_deprecation_spec.yaml
1 changes: 0 error, 0 warning, 1 info
info	[request-property-deprecated] at data/deprecation/request_property_deprecation_spec.yaml
	in API POST /test
		request property 'oldField' deprecated with sunset date%!(EXTRA string='2099-12-31')

Add comment as described above
Missing Scenarios: this implementation is missing several important deprecation scenarios that are handled in the request parameter deprecation checker. Comparing check_request_property_deprecation.go with check_request_parameter_deprecation.go:

Currently Missing:

1. Reactivation Detection ❌

What: Detecting when a deprecated property is un-deprecated (deprecated changes from true to false)
Reference: check_request_parameter_deprecation.go:45-58
Change ID: Should add RequestPropertyReactivatedId
Test: See TestParameterDeprecated_DetectsReactivated in check_request_parameter_deprecation_test.go:169

2. Stability Level Handling ❌

What: Different deprecation policies apply based on stability level (alpha/beta/stable)
Reference: check_request_parameter_deprecation.go:60-66
Impact: Alpha APIs may not require sunset dates, but stable APIs do
Test: See TestBreaking_ParameterDeprecationForAlpha in check_request_parameter_deprecation_test.go:88

3. Sunset Date Validation ❌

What: Ensuring the sunset date is far enough in the future (respecting deprecationDays policy)
Reference: check_request_parameter_deprecation.go:92-106
Change ID: Should add RequestPropertySunsetDateTooSmallId
Breaking Change: This is critical - it catches when developers set unreasonably short deprecation windows
Test: See TestBreaking_ParameterDeprecationWithEarlySunset in check_request_parameter_deprecation_test.go:103

Currently Implemented:

✅ New Deprecation Detection - Lines 38-48
✅ Invalid Sunset Date Format - Handled in getRequestPropertyDeprecationId() at line 88

Recommendation

I suggest enhancing this checker to match the completeness of RequestParameterDeprecationCheck. This would involve:

Adding the missing change IDs:
- RequestPropertyReactivatedId
- RequestPropertySunsetDateTooSmallId
Adding logic to check:
- Reactivation scenario (deprecatedDiff.To == false)
- Stability level via getStabilityLevel(op.Extensions)
- Deprecation policy via getDeprecationDays(config, stability)
- Sunset date timing using date.DaysSince(civil.DateOf(time.Now()))
Adding corresponding tests for each scenario

Note: The same gaps exist in check_response_property_deprecation.go, so both property deprecation checkers would benefit from these enhancements.

jainsachi88 · 2026-01-29T06:05:59Z

Thanks for the detailed feedback!

I’ve implemented the suggested changes.

Fixed failing tests — all test cases now pass successfully.
Removed extra args from message formatting (no %!(EXTRA...) output).
Added missing scenarios in both check_request_property_deprecation.go and check_response_property_deprecation.go:
- Added RequestPropertyReactivatedId and ResponsePropertyReactivatedId for reactivation detection.
- Added RequestPropertySunsetDateTooSmallId and ResponsePropertySunsetDateTooSmallId for short sunset date validation.
- Incorporated stability level handling via getStabilityLevel() and getDeprecationDays().

4.Added corresponding unit tests for all new scenarios (reactivation, stability handling, and early sunset).

Please review the updates

codecov-commenter · 2026-01-31T10:53:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.00%. Comparing base (01f5fb1) to head (8924224).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #782      +/-   ##
==========================================
+ Coverage   88.78%   89.00%   +0.21%     
==========================================
  Files         246      248       +2     
  Lines       12183    12402     +219     
==========================================
+ Hits        10817    11038     +221     
+ Misses        928      926       -2     
  Partials      438      438

Flag	Coverage Δ
unittests	`89.00% <100.00%> (+0.21%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…eprecation

jainsachi88 · 2026-02-02T08:37:08Z

Thanks for the feedback!

I have Added missing patch coverage for property deprecation.
Add some unit test to cover this.

Please review the updates

- Change deprecated message to not include sunset date in localized text, use WithDetails() for sunset/stability info instead - Add missing INFO-level change when no sunset and no deprecation policy - Fix localization format strings to use %s instead of %d - Rewrite tests to use require assertions instead of t.Logf/t.Errorf - Add MessageWithoutDetails tests for both request and response properties Co-Authored-By: Claude Opus 4.5 <[email protected]>

Co-Authored-By: Claude Opus 4.5 <[email protected]>

feature: Add support for showing changelog for deprecated properties

32de02e

reuvenharrison reviewed Jan 24, 2026

View reviewed changes

feature: enhance property deprecation with conditional details

166cbbf

reuvenharrison added 3 commits January 31, 2026 12:46

Merge branch 'main' into feature/Property-deprecation

a15a9c5

update breaking changes examples

61549c2

update check numbers

d26c42a

feature: Added missing tests to improve patch coverage for property d…

f721cad

…eprecation

reuvenharrison and others added 3 commits February 2, 2026 11:18

update breaking changes

6211e66

update deprecation docs to include property deprecation support

8924224

Co-Authored-By: Claude Opus 4.5 <[email protected]>

reuvenharrison merged commit 2c2e2ca into oasdiff:main Feb 2, 2026
8 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feature: Add support for showing changelog for deprecated properties#782

feature: Add support for showing changelog for deprecated properties#782
reuvenharrison merged 9 commits intooasdiff:mainfrom
jainsachi88:feature/Property-deprecation

jainsachi88 commented Jan 23, 2026

Uh oh!

reuvenharrison Jan 24, 2026

Uh oh!

reuvenharrison commented Jan 24, 2026

Uh oh!

jainsachi88 commented Jan 29, 2026

Uh oh!

codecov-commenter commented Jan 31, 2026 •

edited

Loading

Uh oh!

jainsachi88 commented Feb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		// Track reported properties to avoid duplicates per operation
		reportedProperties := make(map[string]bool)

Conversation

jainsachi88 commented Jan 23, 2026

Uh oh!

reuvenharrison Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

reuvenharrison commented Jan 24, 2026

Currently Missing:

Currently Implemented:

Recommendation

Uh oh!

jainsachi88 commented Jan 29, 2026

Uh oh!

codecov-commenter commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jainsachi88 commented Feb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov-commenter commented Jan 31, 2026 •

edited

Loading