Breaking Change in HyperSchema ResponseValidator Status Code Handling

[jvinil05]

Breaking Change in HyperSchema ResponseValidator Status Code Handling

Problem Description

PR #433 introduced a breaking change in the Committee::SchemaValidator::HyperSchema::ResponseValidator that causes validation failures due to overly strict status code matching.

Root Cause

The ResponseValidator now creates validators based on exact status code expectations from link.status_success:

# In ResponseValidator#initialize
@validators[link.status_success] = JsonSchema::Validator.new(target_schema(link))

This creates a rigid mapping:

• rel="create" → expects exactly 201
• rel="empty" → expects exactly 202
• All others → expect exactly 200

The Issue

When the actual response status code doesn't match the expected link.status_success, validation fails with:

raise InvalidResponse, "Invalid response.#{@link.href} status code #{status} definition does not exist" if @validators[status].nil?

This happens because @validators[status] is nil when the status doesn't match the single expected value.

Impact

This breaks backward compatibility for applications where:

1. Create operations return 200 instead of 201
2. Async operations return 200 or 204 instead of 202
3. Existing working code suddenly fails validation after upgrading

Example Failure Scenario

# Schema defines rel="create" (expects 201)
# But application returns 200 for creates
# Result: ValidationError because @validators[200] is nil

Proposed Solutions

Option 1: Flexible Status Code Ranges

Accept multiple valid status codes per relation type:

def acceptable_statuses(rel)
  case rel
  when "create" then [200, 201]
  when "empty" then [200, 202, 204]
  else [200]
  end
end

Option 2: Fallback Validation

Try exact status first, then fall back to common success codes:

validator = @validators[status] || @validators[200] || @validators.values.first

Option 3: Configuration Flag

Add strict_status_codes option to allow users to choose validation strictness.

[geemus]

@jvinil05 Thanks for the detailed report. I believe #453 should address this, could you try it out? I decided to tweak the changes to use the new behavior from #433 for openapi2 (which is what that PR was all about anyway), but still use the old behavior for hyperschema. I'm hoping this solves the problem and strikes the right balance as a kind of partial-revert. Let me know once you've had a chance to dig in. Thanks.

[jvinil05]

@geemus This fix seems to be working for our test suite. thank you for the quick turnaround

[geemus]

released in 5.6.0