Skip to content

Commit d4b5c96

Browse files
robert-hromejrobert-hromej
committed
fix: add relationship linkage for cross-schema has_one/has_many
Fixes a bug where cross-schema relationships were not setting linkage data in JSON:API responses. Related resources appeared in 'included' section but relationships.<name>.data was null, preventing clients from properly linking resources. Changes: - Modified handle_cross_schema_included to convert Array sources to Hash - Added linkage setting in handle_cross_schema_to_one via add_related_identity - Fixed handle_cross_schema_to_many SQL query and linkage - Added source_fragments passing through enhanced_options Tests: - Added 12 comprehensive unit tests covering has_one and has_many - Tests cover Array/Hash sources, null handling, deduplication - Created test fixtures and models for cross-schema scenarios Documentation: - docs/CROSS_SCHEMA_FIX.md - complete problem analysis and solution - CHANGELOG_CROSS_SCHEMA.md - detailed changelog This fix is fully backward compatible.
1 parent 6da78e6 commit d4b5c96

12 files changed

+916
-19
lines changed

‎CHANGELOG_CROSS_SCHEMA.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Changelog: Cross-Schema Relationship Linkage Fix
2+
3+
## Summary
4+
5+
Fixed a critical bug where `has_one` and `has_many` cross-schema relationships were not setting relationship linkage data (`relationships.<name>.data`) in JSON:API responses, even though the related resources were correctly included in the `included` section.
6+
7+
## Changes
8+
9+
### Modified Files
10+
11+
#### `lib/jsonapi/active_relation_resource_patch.rb`
12+
13+
**Changes to `handle_cross_schema_included`:**
14+
- Added support for Array sources (not just Hash)
15+
- Converts Array of ResourceFragments/ResourceIdentities to Hash
16+
- Passes `source_fragments` in enhanced_options to downstream handlers
17+
18+
**Changes to `handle_cross_schema_to_one`:**
19+
- Added linkage setting after creating related resource fragment
20+
- Calls `add_related_identity` on source fragment to populate `relationships.data`
21+
- Added comprehensive debug logging
22+
23+
**Changes to `handle_cross_schema_to_many`:**
24+
- Fixed SQL query to use WHERE clause with foreign_key
25+
- Groups related records by source_id for proper linkage
26+
- Adds linkage for each related resource to source fragment
27+
28+
### New Test Files
29+
30+
#### `test/unit/resource/cross_schema_linkage_test.rb`
31+
32+
Comprehensive unit test suite covering:
33+
34+
**has_one tests:**
35+
- `test_has_one_cross_schema_creates_linkage_data` - Basic linkage creation
36+
- `test_has_one_cross_schema_with_null_foreign_key` - Null foreign key handling
37+
- `test_cross_schema_relationship_with_array_source` - Array source support
38+
- `test_cross_schema_relationship_with_hash_source` - Hash source support
39+
- `test_multiple_candidates_with_same_recruiter` - Deduplication
40+
- `test_cross_schema_included_in_full_serialization` - End-to-end test
41+
- `test_cross_schema_relationships_hash_registration` - Configuration test
42+
- `test_non_cross_schema_relationships_still_work` - Regression test
43+
44+
**has_many tests:**
45+
- `test_has_many_cross_schema_creates_linkage_data` - Basic has_many linkage
46+
- `test_has_many_cross_schema_with_array_source` - Array source with has_many
47+
- `test_has_many_cross_schema_empty_collection` - Empty collection handling
48+
- `test_has_many_cross_schema_deduplication` - Deduplication across multiple sources
49+
50+
#### `test/integration/cross_schema_integration_test.rb`
51+
52+
Integration test placeholders (skipped - require full Rails setup)
53+
54+
### Modified Test Files
55+
56+
#### `test/fixtures/active_record.rb`
57+
58+
Added tables for cross-schema testing:
59+
- `test_candidates` - Primary resource with foreign keys
60+
- `test_users` - Related resource from "different schema"
61+
- `test_locations` - Normal same-schema relationship
62+
- `test_departments` - For has_one cross-schema
63+
- `test_companies` - For has_many cross-schema
64+
65+
#### New Fixtures
66+
67+
- `test/fixtures/test_users.yml`
68+
- `test/fixtures/test_candidates.yml`
69+
- `test/fixtures/test_locations.yml`
70+
- `test/fixtures/test_departments.yml`
71+
72+
### Documentation
73+
74+
#### `docs/CROSS_SCHEMA_FIX.md`
75+
76+
Complete documentation covering:
77+
- Problem description with examples
78+
- Root cause analysis
79+
- Solution implementation details
80+
- Usage examples
81+
- Testing approach
82+
- Migration notes
83+
84+
## Verification
85+
86+
The fix was tested and verified to work in production use cases where:
87+
- Primary resources have `has_one` relationships to resources in different PostgreSQL schemas
88+
- Relationship linkage data now correctly appears in JSON:API responses
89+
- Frontend deserializers can properly link related resources
90+
91+
## Before (Broken)
92+
93+
```json
94+
{
95+
"data": {
96+
"relationships": {
97+
"author": { "data": null }
98+
}
99+
},
100+
"included": [
101+
{ "type": "users", "id": "123" }
102+
]
103+
}
104+
```
105+
106+
## After (Fixed)
107+
108+
```json
109+
{
110+
"data": {
111+
"relationships": {
112+
"author": {
113+
"data": { "type": "users", "id": "123" }
114+
}
115+
}
116+
},
117+
"included": [
118+
{ "type": "users", "id": "123" }
119+
]
120+
}
121+
```
122+
123+
## Backward Compatibility
124+
125+
This fix is fully backward compatible. Existing code using cross-schema relationships will automatically benefit from the fix without any changes required.
126+
127+
## Next Steps
128+
129+
1. Run full test suite to ensure no regressions
130+
2. Create PR to main repository
131+
3. Update version number
132+
4. Release new gem version

‎docs/CROSS_SCHEMA_FIX.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Cross-Schema Relationship Linkage Fix
2+
3+
## Problem
4+
5+
When using `has_one` or `has_many` relationships with the `schema:` option for cross-schema relationships, the relationship linkage data was not being set correctly in the JSON:API response.
6+
7+
**Symptom:**
8+
```json
9+
{
10+
"data": {
11+
"relationships": {
12+
"author": {
13+
"data": null // ❌ Should be { "type": "users", "id": "123" }
14+
}
15+
}
16+
},
17+
"included": [
18+
{
19+
"type": "users", // ✅ Related resource is included
20+
"id": "123",
21+
"attributes": { ... }
22+
}
23+
]
24+
}
25+
```
26+
27+
The related resource appears in the `included` section, but `relationships.author.data` is `null`, preventing clients from properly linking the resources.
28+
29+
## Root Cause
30+
31+
The `handle_cross_schema_to_one` and `handle_cross_schema_to_many` methods in `active_relation_resource_patch.rb` were:
32+
33+
1. ✅ Correctly loading related resources from cross-schema tables
34+
2. ✅ Correctly adding them to `included` section
35+
3. ❌ **NOT** setting the relationship linkage data in the source resource
36+
37+
This prevented JSON:API clients from establishing the relationship between the primary resource and the included resource.
38+
39+
## Solution
40+
41+
Modified `lib/jsonapi/active_relation_resource_patch.rb` to:
42+
43+
### 1. Handle Array sources (not just Hash)
44+
45+
The `handle_cross_schema_included` method now converts Array sources to a Hash of fragments:
46+
47+
```ruby
48+
source_fragments_hash = {}
49+
source_ids = if source.is_a?(Hash)
50+
source_fragments_hash = source
51+
source.keys.map(&:id)
52+
elsif source.is_a?(Array)
53+
source.each do |item|
54+
if item.respond_to?(:identity)
55+
source_fragments_hash[item.identity] = item
56+
elsif item.is_a?(JSONAPI::ResourceIdentity)
57+
source_fragments_hash[item] = JSONAPI::ResourceFragment.new(item)
58+
end
59+
end
60+
# ...
61+
end
62+
```
63+
64+
### 2. Add linkage to source fragments
65+
66+
In both `handle_cross_schema_to_one` and `handle_cross_schema_to_many`, after creating the related resource fragment, we now add the linkage to the source fragment:
67+
68+
```ruby
69+
# Create fragment for related resource
70+
fragments[rid] = JSONAPI::ResourceFragment.new(rid, resource: resource)
71+
72+
# Add linkage to source fragment
73+
source_rid = JSONAPI::ResourceIdentity.new(self, source_resource.id)
74+
if options[:source_fragments] && options[:source_fragments][source_rid]
75+
options[:source_fragments][source_rid].add_related_identity(relationship.name, rid)
76+
end
77+
```
78+
79+
This ensures that the `relationships.<name>.data` field is populated correctly in the serialized output.
80+
81+
## Testing
82+
83+
### Unit Tests
84+
85+
Created comprehensive unit tests in `test/unit/resource/cross_schema_linkage_test.rb`:
86+
87+
- `test_has_one_cross_schema_creates_linkage_data` - Verifies linkage data is set for has_one
88+
- `test_has_one_cross_schema_with_null_foreign_key` - Handles null foreign keys gracefully
89+
- `test_cross_schema_relationship_with_array_source` - Tests Array source handling
90+
- `test_cross_schema_relationship_with_hash_source` - Tests Hash source handling
91+
- `test_multiple_candidates_with_same_recruiter` - Tests deduplication
92+
- `test_cross_schema_included_in_full_serialization` - End-to-end serialization test
93+
- `test_cross_schema_relationships_hash_registration` - Verifies configuration
94+
- `test_non_cross_schema_relationships_still_work` - Regression test
95+
96+
### Test Fixtures
97+
98+
Created test fixtures:
99+
- `test_users.yml` - User data from "another schema"
100+
- `test_candidates.yml` - Primary resources with foreign keys
101+
- `test_locations.yml` - Normal same-schema relationships
102+
- `test_departments.yml` - For has_many testing
103+
104+
## Usage
105+
106+
Define cross-schema relationships using the `schema:` option:
107+
108+
### has_one example:
109+
110+
```ruby
111+
class CandidateResource < JSONAPI::ActiveRelationResource
112+
attributes :full_name, :email
113+
114+
has_one :author,
115+
class_name: 'User',
116+
schema: 'auth_schema',
117+
exclude_links: :default,
118+
always_include_linkage_data: true
119+
end
120+
```
121+
122+
### has_many example:
123+
124+
```ruby
125+
class DepartmentResource < JSONAPI::ActiveRelationResource
126+
attributes :name
127+
128+
has_many :members,
129+
class_name: 'User',
130+
schema: 'auth_schema',
131+
exclude_links: :default
132+
end
133+
```
134+
135+
## Files Modified
136+
137+
- `lib/jsonapi/active_relation_resource_patch.rb` - Core fix for linkage
138+
- `test/unit/resource/cross_schema_linkage_test.rb` - Comprehensive unit tests
139+
- `test/unit/resource/cross_schema_test.rb` - Original cross-schema tests
140+
- `test/fixtures/active_record.rb` - Added test tables
141+
- `test/fixtures/test_*.yml` - Test data fixtures
142+
143+
## Running Tests
144+
145+
```bash
146+
cd jsonapi-resources
147+
bundle install
148+
bundle exec rake test TEST=test/unit/resource/cross_schema_linkage_test.rb
149+
```
150+
151+
## Migration Notes
152+
153+
Existing applications using cross-schema relationships will automatically benefit from this fix. No changes to application code are required - the linkage data will now be correctly populated in responses.

0 commit comments

Comments
 (0)