Skip to content

A platform for community discussion. Free, open, simple.

DEV: Support resource type renames in JSON:API versions (#43553)

Loïc Guitautf4468e7f4e9d
diff --git a/lib/json_api_kit/document/relationship_object.rb b/lib/json_api_kit/document/relationship_object.rb
index 0faaee7eaeb..952fe6f67c1 100644
--- a/lib/json_api_kit/document/relationship_object.rb
+++ b/lib/json_api_kit/document/relationship_object.rb
@@ -4,10 +4,11 @@ module JsonApiKit
class Document
class RelationshipObject
delegate :pages, to: :linkage, private: true
+ delegate :urls, :glossary, to: :client, private: true
- def initialize(linkage, urls:, owner:, name:)
+ def initialize(linkage, client:, owner:, name:)
@linkage = linkage
- @urls = urls
+ @client = client
@owner = owner
@name = name
end
@@ -16,9 +17,13 @@ module JsonApiKit
private
- attr_reader :linkage, :urls, :owner, :name
+ attr_reader :linkage, :client, :owner, :name
- def data = linkage.collapse { it.identity.to_h }
+ def data = linkage.collapse { identifier(it) }
+
+ def identifier(record)
+ { type: glossary.member_type(record.type), id: record.id }
+ end
def links = { self: relationship_url.to_s, related: related_url.to_s }.merge(page_links)
diff --git a/lib/json_api_kit/document/resource_object.rb b/lib/json_api_kit/document/resource_object.rb
index 2cbaa696657..2c62ff18c2d 100644
--- a/lib/json_api_kit/document/resource_object.rb
+++ b/lib/json_api_kit/document/resource_object.rb
@@ -3,7 +3,7 @@
module JsonApiKit
class Document
class ResourceObject
- delegate :type, :id, to: :record, private: true
+ delegate :id, to: :record, private: true
delegate :glossary, :urls, to: :client, private: true
def initialize(record, client:, fieldsets:, meta: {})
@@ -19,7 +19,9 @@ module JsonApiKit
attr_reader :record, :client, :fieldsets, :meta
- def relationship(value) = Name::Relationship.new(value:, type:)
+ def type = glossary.member_type(record.type)
+
+ def relationship(value) = Name::Relationship.new(value:, type: record.type)
def member_value(name) = glossary.member_name(name).value
@@ -30,7 +32,7 @@ module JsonApiKit
def relationships
record.relationships.to_h do |name, linkage|
member = member_value(relationship(name))
- [member, RelationshipObject.new(linkage, urls:, owner: record, name: member).to_h]
+ [member, RelationshipObject.new(linkage, client:, owner: record, name: member).to_h]
end
end
diff --git a/lib/json_api_kit/glossary.rb b/lib/json_api_kit/glossary.rb
index 6d907440c63..99a8165500f 100644
--- a/lib/json_api_kit/glossary.rb
+++ b/lib/json_api_kit/glossary.rb
@@ -56,13 +56,17 @@ module JsonApiKit
def declared_attributes(attributes)
attributes.each_key { declared_name(it) }
- rules.reduce(attributes) { |result, rule| rule.declared_attributes(result) }
- rescue VersionChange::Converter::Failure => failure
- raise BadValue.new(failure.names.map { member_name(it) })
+ rules
+ .each_with_index
+ .reduce(attributes) do |result, (rule, index)|
+ rule.declared_attributes(result)
+ rescue VersionChange::Converter::Failure => failure
+ raise BadValue.new(member_names_before(failure.names, index))
+ end
end
def declared_name(name)
- declared_names[name] ||= rules.reduce(name) { |result, rule| rule.declared_name(result) }
+ declared_names[name] ||= declare_name(name, rules)
rescue Correction => correction
raise NotAMemberName.new(name, member_name(correction.name))
end
@@ -73,6 +77,8 @@ module JsonApiKit
.reduce(name) { |result, rule| rule.member_name(result) }
end
+ def member_type(type) = member_name(Name::Type.new(value: type)).value
+
def member_attributes(attributes)
rules.reverse_each.reduce(attributes) { |result, rule| rule.member_attributes(result) }
end
@@ -80,5 +86,25 @@ module JsonApiKit
private
attr_reader :rules, :declared_names, :member_names
+
+ def member_names_before(names, rule_index)
+ rules
+ .take(rule_index)
+ .reverse_each
+ .reduce(names) { |result, rule| result.map { rule.member_name(it) } }
+ end
+
+ def declare_name(name, remaining_rules)
+ remaining_rules.reduce(name) do |result, rule|
+ rule.declared_name(result)
+ rescue Correction => correction
+ raise Correction.new(
+ declare_name(
+ correction.name,
+ remaining_rules.drop(remaining_rules.index(rule) + 1),
+ ),
+ )
+ end
+ end
end
end
diff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rb
index 57eb5d3e4d0..bf7fdeedbe1 100644
--- a/lib/json_api_kit/glossary/version_rule.rb
+++ b/lib/json_api_kit/glossary/version_rule.rb
@@ -8,7 +8,13 @@ module JsonApiKit
end
def declared_attributes(attributes)
- changes.reduce(attributes) { |result, change| change.current_attributes(result) }
+ changes
+ .each_with_index
+ .reduce(attributes) do |result, (change, index)|
+ change.current_attributes(result)
+ rescue VersionChange::Converter::Failure => failure
+ raise failure.convert_names { member_names(it, changes: changes.take(index)) }
+ end
end
def declared_name(name)
@@ -31,7 +37,7 @@ module JsonApiKit
def current_name(name) = changes.reduce(name) { |result, change| change.current(result) }
- def member_names(name)
+ def member_names(name, changes: self.changes)
changes
.reverse_each
.reduce([name]) { |names, change| names.flat_map { change.previous_names(it) } }
diff --git a/lib/json_api_kit/name.rb b/lib/json_api_kit/name.rb
index 3b2d4022fb1..b18b5fc563f 100644
--- a/lib/json_api_kit/name.rb
+++ b/lib/json_api_kit/name.rb
@@ -4,6 +4,8 @@ module JsonApiKit
module Name
def convert = with(value: yield(value))
+ def convert_type = self
+
def to_s = value
end
end
diff --git a/lib/json_api_kit/name/anchor.rb b/lib/json_api_kit/name/anchor.rb
index dd04223ccdb..88518c6d02d 100644
--- a/lib/json_api_kit/name/anchor.rb
+++ b/lib/json_api_kit/name/anchor.rb
@@ -2,6 +2,6 @@
module JsonApiKit
module Name
- Anchor = Data.define(:value, :type) { include Name }
+ Anchor = Data.define(:value, :type) { include Name::ResourceScope }
end
end
diff --git a/lib/json_api_kit/name/field.rb b/lib/json_api_kit/name/field.rb
index f94eff145ad..763ac134b24 100644
--- a/lib/json_api_kit/name/field.rb
+++ b/lib/json_api_kit/name/field.rb
@@ -2,6 +2,6 @@
module JsonApiKit
module Name
- Field = Data.define(:value, :type) { include Name }
+ Field = Data.define(:value, :type) { include Name::ResourceScope }
end
end
diff --git a/lib/json_api_kit/name/filter.rb b/lib/json_api_kit/name/filter.rb
index 95f29c8a40c..c8d2af6fdff 100644
--- a/lib/json_api_kit/name/filter.rb
+++ b/lib/json_api_kit/name/filter.rb
@@ -2,6 +2,6 @@
module JsonApiKit
module Name
- Filter = Data.define(:value, :type) { include Name }
+ Filter = Data.define(:value, :type) { include Name::ResourceScope }
end
end
diff --git a/lib/json_api_kit/name/relationship.rb b/lib/json_api_kit/name/relationship.rb
index 4c5c75f9c71..774601f7ab2 100644
--- a/lib/json_api_kit/name/relationship.rb
+++ b/lib/json_api_kit/name/relationship.rb
@@ -2,6 +2,6 @@
module JsonApiKit
module Name
- Relationship = Data.define(:value, :type) { include Name }
+ Relationship = Data.define(:value, :type) { include Name::ResourceScope }
end
end
diff --git a/lib/json_api_kit/name/resource_scope.rb b/lib/json_api_kit/name/resource_scope.rb
new file mode 100644
index 00000000000..589ce7e53e5
--- /dev/null
+++ b/lib/json_api_kit/name/resource_scope.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ module ResourceScope
+ include Name
+
+ def convert(&) = super.convert_type(&)
+
+ def convert_type = with(type: yield(type))
+ end
+ end
+end
diff --git a/lib/json_api_kit/name/sort.rb b/lib/json_api_kit/name/sort.rb
index 4525461b3e8..62fd3035007 100644
--- a/lib/json_api_kit/name/sort.rb
+++ b/lib/json_api_kit/name/sort.rb
@@ -2,6 +2,6 @@
module JsonApiKit
module Name
- Sort = Data.define(:value, :type) { include Name }
+ Sort = Data.define(:value, :type) { include Name::ResourceScope }
end
end
diff --git a/lib/json_api_kit/name/type.rb b/lib/json_api_kit/name/type.rb
new file mode 100644
index 00000000000..1f733138a62
--- /dev/null
+++ b/lib/json_api_kit/name/type.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Type =
+ Data.define(:value) do
+ include Name
+
+ def convert_type(&) = convert(&)
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/contract/error.rb b/lib/json_api_kit/request/contract/error.rb
index e9976fc74b1..07bdeb06ca0 100644
--- a/lib/json_api_kit/request/contract/error.rb
+++ b/lib/json_api_kit/request/contract/error.rb
@@ -33,6 +33,8 @@ module JsonApiKit
def key = member_value(options[:key])
+ def resource_type = glossary.member_type(options[:type])
+
def member_parameter(member = name) = parameter.member(member)
def window_parameters = base.page.window_names.map { page_parameter(it) }
diff --git a/lib/json_api_kit/request/contract/mapper.rb b/lib/json_api_kit/request/contract/mapper.rb
index 02765e4910f..e772e4eaf4f 100644
--- a/lib/json_api_kit/request/contract/mapper.rb
+++ b/lib/json_api_kit/request/contract/mapper.rb
@@ -84,9 +84,9 @@ module JsonApiKit
%i[fields bad_value] => {
title: "Invalid fields value",
detail: ->(error) do
- "#{error.member_parameter(error.options[:type])} must be a list of field names."
+ "#{error.member_parameter(error.resource_type)} must be a list of field names."
end,
- source: ->(error) { error.member_parameter(error.options[:type]) },
+ source: ->(error) { error.member_parameter(error.resource_type) },
},
%i[sort bad_shape] => {
title: "Invalid sort parameter",
diff --git a/lib/json_api_kit/request/family/fields.rb b/lib/json_api_kit/request/family/fields.rb
index bd44f82d7b6..5887811dbac 100644
--- a/lib/json_api_kit/request/family/fields.rb
+++ b/lib/json_api_kit/request/family/fields.rb
@@ -6,11 +6,17 @@ module JsonApiKit
class Fields < Family
def declared_value(value, path)
return value unless value.is_a?(Hash)
- value.to_h { |type, raw| [type, declared_fieldset(raw, type, path + [type])] }
+ value.to_h do |type, raw|
+ [declared_type(type, path), declared_fieldset(raw, type, path + [type])]
+ end
end
private
+ def declared_type(type, path)
+ declared_name(Name::Type.new(value: type), path + [type])
+ end
+
def declared_fieldset(raw, type, path)
Fieldsets::Fieldset
.parse(raw)
diff --git a/lib/json_api_kit/request/parameters.rb b/lib/json_api_kit/request/parameters.rb
index ad8a66d13c0..380b9481f9a 100644
--- a/lib/json_api_kit/request/parameters.rb
+++ b/lib/json_api_kit/request/parameters.rb
@@ -30,7 +30,9 @@ module JsonApiKit
attr_reader :raw, :glossary, :resource
- def family_for(key) = FAMILIES.fetch(key, Family::Other).new(glossary:, type: resource.type)
+ def family_for(key) = FAMILIES.fetch(key, Family::Other).new(glossary:, type: member_type)
+
+ def member_type = glossary.member_type(resource.type)
def declared_name(family)
glossary.declared_name(Name::Member.new(value: family)).value
diff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rb
index c43071a7e28..7d93b3f2c6a 100644
--- a/lib/json_api_kit/version_change.rb
+++ b/lib/json_api_kit/version_change.rb
@@ -37,6 +37,15 @@ module JsonApiKit
def transformations = @transformations ||= []
+ def renamed_type(from:, to:)
+ type_renames << TypeRename.new(
+ from: Name::Type.new(value: from.to_s),
+ to: Name::Type.new(value: to.to_s),
+ )
+ end
+
+ def type_renames = @type_renames ||= []
+
private
def change_in(source)
@@ -47,14 +56,16 @@ module JsonApiKit
end
end
- delegate :version, :description, :transformations, to: :class
+ delegate :version, :description, :transformations, :type_renames, to: :class
attr_reader :source
def initialize(source)
@source = source
- @upward = index_by(&:previous_names)
- @downward = index_by { [it.current] }
+ @upward = index_by(transformations, &:previous_names)
+ @downward = index_by(transformations) { [it.current] }
+ @type_upward = index_by(type_renames, &:previous_names)
+ @type_downward = index_by(type_renames) { [it.current] }
end
def verify!
@@ -72,25 +83,42 @@ module JsonApiKit
raise ArgumentError, "The file name must start with the version #{version}: #{source}."
end
- def current(name) = upward[name].current
+ def current(name) = upward[current_type(name)].current
def current_attributes(attributes)
- attributes.keys.map { upward[it] }.uniq.flat_map { it.current_pairs(attributes) }.to_h
+ current_values(attributes.transform_keys { current_type(it) })
+ rescue Converter::Failure => failure
+ raise failure.convert_names { previous_type(it) }
end
- def previous(name) = downward[name].previous_names.first
+ def previous(name) = previous_names(name).first
- def previous_names(name) = downward[name].previous_names
+ def previous_names(name) = downward[name].previous_names.map { previous_type(it) }
def previous_attributes(attributes)
- attributes.flat_map { |name, value| downward[name].previous_pairs(value) }.to_h
+ attributes
+ .flat_map { |name, value| downward[name].previous_pairs(value) }
+ .to_h
+ .transform_keys { previous_type(it) }
end
private
- attr_reader :upward, :downward
+ attr_reader :upward, :downward, :type_upward, :type_downward
+
+ def current_type(name)
+ name.convert_type { type_upward[Name::Type.new(value: it)].current.value }
+ end
+
+ def previous_type(name)
+ name.convert_type { type_downward[Name::Type.new(value: it)].previous_names.first.value }
+ end
+
+ def current_values(attributes)
+ attributes.keys.map { upward[it] }.uniq.flat_map { it.current_pairs(attributes) }.to_h
+ end
- def index_by(&names)
+ def index_by(transformations, &names)
transformations
.flat_map { |transformation| names.call(transformation).map { [it, transformation] } }
.to_h
@@ -98,7 +126,7 @@ module JsonApiKit
end
def duplicate_name(&)
- transformations.flat_map(&).tally.detect { |_name, count| count > 1 }&.first
+ (transformations + type_renames).flat_map(&).tally.detect { |_name, count| count > 1 }&.first
end
end
end
diff --git a/lib/json_api_kit/version_change/converter.rb b/lib/json_api_kit/version_change/converter.rb
index a46b3515b18..4869944dc44 100644
--- a/lib/json_api_kit/version_change/converter.rb
+++ b/lib/json_api_kit/version_change/converter.rb
@@ -10,6 +10,8 @@ module JsonApiKit
@names = names
super("cannot convert the value of #{names.join(", ")}")
end
+
+ def convert_names(&) = self.class.new(names.flat_map(&))
end
def initialize(direction, callable, names)
diff --git a/lib/json_api_kit/version_change/type_rename.rb b/lib/json_api_kit/version_change/type_rename.rb
new file mode 100644
index 00000000000..5dfdfe36ba7
--- /dev/null
+++ b/lib/json_api_kit/version_change/type_rename.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ TypeRename =
+ Data.define(:from, :to) do
+ def current = to
+
+ def previous_names = [from]
+ end
+ end
+end
diff --git a/spec/integration/json_api_kit/renamed_types_spec.rb b/spec/integration/json_api_kit/renamed_types_spec.rb
new file mode 100644
index 00000000000..70613ffd41c
--- /dev/null
+++ b/spec/integration/json_api_kit/renamed_types_spec.rb
@@ -0,0 +1,470 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+module JsonApiKitSpec
+ class RenamedTypesController < JsonApiKit::BaseController
+ resource :topics
+ end
+
+ class RenameDiscussionFields < JsonApiKit::VersionChange
+ version "2026-09-01"
+ description "Discussion fields use new names."
+
+ resource :discussion_threads do
+ renamed_attribute from: :words,
+ to: :heading,
+ up: ->(words) { words.to_a.join(" ") },
+ down: ->(heading) { heading.to_s.split(" ") }
+ merged_attributes from: %i[posted_date posted_time],
+ to: :posted_at,
+ up: ->(date, time) { Time.zone.parse("#{date}T#{time}Z") },
+ down: ->(time) { [time.to_date.iso8601, time.strftime("%H:%M:%S")] }
+ renamed_sort from: :bumped_at, to: :last_posted_at
+ renamed_filter from: :name, to: :title
+ end
+ end
+
+ class RenameDiscussionsToArticles < JsonApiKit::VersionChange
+ version "2026-09-02"
+ description "Discussions become articles."
+
+ resource :articles do
+ renamed_attribute from: :heading, to: :subject
+ end
+
+ renamed_type from: :discussion_threads, to: :articles
+ renamed_type from: :authors, to: :users
+ renamed_type from: :teams, to: :groups
+ end
+
+ class RenameArticlesToTopics < JsonApiKit::VersionChange
+ version "2026-09-03"
+ description "Articles become topics."
+
+ renamed_type from: :articles, to: :topics
+ end
+
+ class RenameTopicFieldsAfterType < JsonApiKit::VersionChange
+ version "2026-09-04"
+ description "Topic fields use their current names."
+
+ resource :topics do
+ renamed_attribute from: :subject, to: :title
+ renamed_attribute from: :posted_at, to: :created_at
+ end
+ end
+end
+
+RSpec.describe "JSON:API type renames", type: :request do
+ include_context "with a listing of topics"
+
+ let(:changes) do
+ [
+ JsonApiKitSpec::RenameDiscussionFields,
+ JsonApiKitSpec::RenameDiscussionsToArticles,
+ JsonApiKitSpec::RenameArticlesToTopics,
+ JsonApiKitSpec::RenameTopicFieldsAfterType,
+ ].map { it.new(__FILE__) }
+ end
+ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE.to_s }
+ let(:parsed_body) { JSON.parse(response.body) }
+ let(:primary) { parsed_body.fetch("data").first }
+ let(:attributes) { primary.fetch("attributes") }
+ let(:ids) { parsed_body.fetch("data").map { it.fetch("id") } }
+ let(:error) { parsed_body.fetch("errors").sole }
+ let(:author) { newest.user }
+ let(:group_object) do
+ parsed_body.fetch("included").detect { it["id"] == group.id.to_s && it["type"] == "teams" }
+ end
+ let(:author_object) do
+ parsed_body.fetch("included").detect { it["id"] == author.id.to_s && it["type"] == "authors" }
+ end
+
+ fab!(:group)
+
+ before do
+ group.add(author)
+ oldest.update_columns(last_posted_at: Time.utc(2026, 8, 3))
+ middle.update_columns(last_posted_at: Time.utc(2026, 8, 1))
+ newest.update_columns(last_posted_at: Time.utc(2026, 8, 2))
+ freeze_time(Date.new(2026, 9, 5))
+ allow(JsonApiKit::VersionChange).to receive(:all).and_return(changes)
+ Rails.application.routes.disable_clear_and_finalize = true
+ Rails.application.routes.draw do
+ get "/api/topics" => "json_api_kit_spec/renamed_types#index"
+ get "/api/topics/:id" => "json_api_kit_spec/renamed_types#show"
+ end
+ Rails.application.routes.disable_clear_and_finalize = false
+ get "/api/topics", headers: { "HTTP_API_VERSION" => version }, params: query
+ end
+
+ after { Rails.application.reload_routes! }
+
+ it "sends the historical type with its casing" do
+ expect(primary.fetch("type")).to eq("discussionThreads")
+ end
+
+ it "reverses field changes across both type changes" do
+ expect(attributes).to eq(
+ "words" => newest.title.split(" "),
+ "postedDate" => "2026-08-03",
+ "postedTime" => "00:00:00",
+ )
+ end
+
+ it "keeps the current resource URL" do
+ expect(URI(primary.dig("links", "self")).path).to eq("/api/topics/#{newest.id}")
+ end
+
+ context "when the client follows the resource URL" do
+ before { get primary.dig("links", "self"), headers: { "HTTP_API_VERSION" => version } }
+
+ it "serves the historical representation" do
+ expect(JSON.parse(response.body).fetch("data")).to include(
+ "type" => "discussionThreads",
+ "id" => newest.id.to_s,
+ )
+ end
+ end
+
+ context "when the request includes renamed related resources" do
+ let(:query) { { "include" => "user.groups,category" } }
+
+ it "uses the historical type in to-one linkage" do
+ expect(primary.dig("relationships", "user", "data")).to eq(
+ "type" => "authors",
+ "id" => author.id.to_s,
+ )
+ end
+
+ it "uses the historical type in to-many linkage" do
+ expect(author_object.dig("relationships", "groups", "data")).to include(
+ "type" => "teams",
+ "id" => group.id.to_s,
+ )
+ end
+
+ it "includes the resources named by the linkage" do
+ expect(parsed_body.fetch("included")).to include(
+ a_hash_including("type" => "authors", "id" => author.id.to_s),
+ a_hash_including("type" => "teams", "id" => group.id.to_s),
+ )
+ end
+
+ it "preserves an unrelated resource" do
+ expect(parsed_body.fetch("included")).to include(
+ a_hash_including(
+ "type" => "categories",
+ "id" => newest.category.id.to_s,
+ "attributes" => {
+ "name" => newest.category.name,
+ },
+ ),
+ )
+ end
+
+ context "when the fieldsets exclude related attributes" do
+ let(:query) { super().merge("fields" => { "authors" => "groups", "teams" => "" }) }
+
+ it "keeps the included identities without their attributes" do
+ expect(author_object).not_to have_key("attributes")
+ end
+
+ it "excludes the attributes of the to-many resource" do
+ expect(group_object).not_to have_key("attributes")
+ end
+
+ it "keeps the to-many linkage without related attributes" do
+ expect(author_object.dig("relationships", "groups", "data")).to include(
+ "type" => "teams",
+ "id" => group.id.to_s,
+ )
+ end
+
+ it "keeps the relationship linkage" do
+ expect(primary.dig("relationships", "user", "data")).to eq(
+ "type" => "authors",
+ "id" => author.id.to_s,
+ )
+ end
+ end
+ end
+
+ context "when the request selects a historical field" do
+ let(:query) { { "fields" => { "discussionThreads" => "words" } } }
+
+ it "sends only the selected field" do
+ expect(attributes).to eq("words" => newest.title.split(" "))
+ end
+ end
+
+ context "when the request selects one component of a merge" do
+ let(:query) { { "fields" => { "discussionThreads" => "postedDate" } } }
+
+ it "sends only the selected component" do
+ expect(attributes).to eq("postedDate" => "2026-08-03")
+ end
+ end
+
+ context "when the fieldset uses the current type before its introduction" do
+ let(:query) { { "fields" => { "topics" => "words" } } }
+
+ it "corrects the type in the client's vocabulary" do
+ expect(error).to include(
+ "detail" => "Use discussionThreads, not topics.",
+ "source" => {
+ "parameter" => "fields[topics]",
+ },
+ )
+ end
+ end
+
+ context "when the fieldset uses a later field name" do
+ let(:query) { { "fields" => { "discussionThreads" => "title" } } }
+
+ it "corrects the field under the historical type" do
+ expect(error).to include(
+ "detail" => "Use words, not title.",
+ "source" => {
+ "parameter" => "fields[discussionThreads]",
+ },
+ )
+ end
+ end
+
+ context "when the fieldset has an invalid value" do
+ let(:query) { { "fields" => { "discussionThreads" => { "bad" => "value" } } } }
+
+ it "names the historical type in the error" do
+ expect(error).to include(
+ "detail" => "fields[discussionThreads] must be a list of field names.",
+ "source" => {
+ "parameter" => "fields[discussionThreads]",
+ },
+ )
+ end
+ end
+
+ context "when a current field also has incorrect casing" do
+ let(:query) { { "fields" => { "discussionThreads" => "created_at" } } }
+
+ it "suggests a field name valid for the historical type" do
+ expect(error).to include(
+ "detail" => "Use postedDate, not created_at.",
+ "source" => {
+ "parameter" => "fields[discussionThreads]",
+ },
+ )
+ end
+ end
+
+ context "when the request sorts by a historical attribute" do
+ let(:query) { { "sort" => "words" } }
+
+ it "applies the attribute changes before and after the type changes" do
+ expect(ids).to eq([oldest.id.to_s, newest.id.to_s, middle.id.to_s])
+ end
+ end
+
+ context "when the request uses a historical sort name" do
+ let(:query) { { "sort" => "bumpedAt" } }
+
+ it "applies the sort change before the type changes" do
+ expect(ids).to eq([middle.id.to_s, newest.id.to_s, oldest.id.to_s])
+ end
+ end
+
+ context "when the request uses a historical filter name" do
+ let(:query) { { "filter" => { "name" => newest.title } } }
+
+ it "applies the filter change before the type changes" do
+ expect(ids).to contain_exactly(newest.id.to_s)
+ end
+ end
+
+ context "when the request anchors on a converted historical attribute" do
+ let(:query) do
+ {
+ "sort" => "words",
+ "page" => {
+ "anchor" => {
+ "words" => newest.title.split(" "),
+ },
+ "beforeSize" => "1",
+ "afterSize" => "0",
+ },
+ }
+ end
+
+ it "converts the anchor across the type changes" do
+ expect(ids).to eq([oldest.id.to_s, newest.id.to_s])
+ end
+ end
+
+ context "when the request anchors on merged historical attributes" do
+ let(:query) do
+ {
+ "sort" => "postedDate,postedTime",
+ "page" => {
+ "anchor" => {
+ "postedDate" => "2026-08-02",
+ "postedTime" => "00:00:00",
+ },
+ "beforeSize" => "1",
+ "afterSize" => "0",
+ },
+ }
+ end
+
+ it "merges the anchor before the type changes" do
+ expect(ids).to eq([oldest.id.to_s, middle.id.to_s])
+ end
+ end
+
+ context "when the request includes the same author through two paths" do
+ let(:query) { { "include" => "user,posts.user" } }
+ let(:included_authors) do
+ parsed_body
+ .fetch("included")
+ .select { |resource| resource["type"] == "authors" && resource["id"] == author.id.to_s }
+ end
+
+ fab!(:post) { Fabricate(:post, topic: newest, user: newest.user) }
+
+ it "includes one resource for that identity" do
+ expect(included_authors).to contain_exactly(
+ a_hash_including("type" => "authors", "id" => author.id.to_s),
+ )
+ end
+ end
+
+ context "when an anchor does not match the historical sort" do
+ let(:query) do
+ {
+ "sort" => "words",
+ "page" => {
+ "anchor" => {
+ "postedDate" => "2026-08-02",
+ "postedTime" => "00:00:00",
+ },
+ },
+ }
+ end
+
+ it "uses historical names in the error" do
+ expect(error).to include(
+ "detail" => "The anchor is postedDate, but this request sorts by words.",
+ "source" => {
+ "parameter" => "page[anchor][postedDate]",
+ },
+ )
+ end
+ end
+
+ context "when the anchor value cannot be converted" do
+ let(:query) { { "sort" => "words", "page" => { "anchor" => { "words" => "invalid" } } } }
+
+ it "uses the historical name in the conversion error" do
+ expect(error).to include(
+ "detail" => "This version cannot convert the value of words.",
+ "source" => {
+ "parameter" => "page[anchor]",
+ },
+ )
+ end
+ end
+
+ context "when a later change reuses the converter's type name" do
+ let(:changes) { [earlier_change, *super(), reuse_change] }
+ let(:earlier_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ version "2026-09-01"
+ description "Discussion fields change before their values are converted."
+
+ resource :discussion_threads do
+ renamed_attribute from: :title_words, to: :words
+ renamed_attribute from: :posting_date, to: :posted_date
+ renamed_attribute from: :posting_time, to: :posted_time
+ end
+ end
+ .new(__FILE__)
+ end
+ let(:reuse_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ version "2026-09-05"
+ description "Another resource uses the former discussion type."
+
+ renamed_type from: :saved_searches, to: :discussion_threads
+ end
+ .new(__FILE__)
+ end
+ let(:query) do
+ { "sort" => "titleWords", "page" => { "anchor" => { "titleWords" => "invalid" } } }
+ end
+
+ it "reports the field name the client supplied" do
+ expect(error).to include(
+ "detail" => "This version cannot convert the value of titleWords.",
+ "source" => {
+ "parameter" => "page[anchor]",
+ },
+ )
+ end
+
+ context "when the converter merges several fields" do
+ let(:query) do
+ {
+ "sort" => "postingDate,postingTime",
+ "page" => {
+ "anchor" => {
+ "postingDate" => "2026-13-45",
+ "postingTime" => "00:00:00",
+ },
+ },
+ }
+ end
+
+ it "reports every input field in the client's vocabulary" do
+ expect(error).to include(
+ "detail" => "This version cannot convert the value of postingDate, postingTime.",
+ "source" => {
+ "parameter" => "page[anchor]",
+ },
+ )
+ end
+ end
+ end
+
+ context "when the pin follows the first type change" do
+ let(:version) { "2026-09-02" }
+ let(:query) { { "fields" => { "articles" => "subject" } } }
+
+ it "sends the intermediate type and field name" do
+ expect(primary).to include(
+ "type" => "articles",
+ "attributes" => {
+ "subject" => newest.title,
+ },
+ )
+ end
+ end
+
+ context "when the pin follows all changes" do
+ let(:version) { "2026-09-04" }
+ let(:query) { { "fields" => { "topics" => "title,user" }, "include" => "user.groups" } }
+
+ it "sends the current type and field name" do
+ expect(primary).to include("type" => "topics", "attributes" => { "title" => newest.title })
+ end
+
+ it "sends the current linkage type" do
+ expect(primary.dig("relationships", "user", "data")).to eq(
+ "type" => "users",
+ "id" => author.id.to_s,
+ )
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/document/relationship_object_spec.rb b/spec/lib/json_api_kit/document/relationship_object_spec.rb
index a0a5805ecc3..51c296994d2 100644
--- a/spec/lib/json_api_kit/document/relationship_object_spec.rb
+++ b/spec/lib/json_api_kit/document/relationship_object_spec.rb
@@ -1,12 +1,14 @@
# frozen_string_literal: true
RSpec.describe JsonApiKit::Document::RelationshipObject do
- subject(:relationship_object) { described_class.new(linkage, urls:, owner:, name: "posts") }
+ subject(:relationship_object) { described_class.new(linkage, client:, owner:, name: "posts") }
fab!(:author, :user)
fab!(:topic)
let(:guardian) { Guardian.new }
+ let(:glossary) { JsonApiKit::Glossary.kit }
+ let(:client) { JsonApiKit::Client.new(guardian:, glossary:, urls:) }
let(:urls) do
JsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/topics")
end
@@ -44,6 +46,26 @@ RSpec.describe JsonApiKit::Document::RelationshipObject do
let(:related_url) { "https://example.com/api/topics/#{topic.id}/posts" }
describe "#to_h" do
+ context "when the type has a historical name" do
+ let(:glossary) { JsonApiKit::Glossary.resource(JsonApiKit::Timeline::FIRST_RELEASE) }
+ let(:version_change) do
+ Class
+ .new(JsonApiKit::VersionChange) { renamed_type from: :topic_authors, to: :users }
+ .new(__FILE__)
+ end
+
+ before { allow(JsonApiKit::VersionChange).to receive(:after).and_return([version_change]) }
+
+ it "translates the linkage type" do
+ expect(relationship_object.to_h[:data]).to eq(type: "topicAuthors", id: author.id.to_s)
+ end
+
+ it "keeps the record identity in the current vocabulary" do
+ relationship_object.to_h
+ expect(record.identity.to_h).to eq(type: "users", id: author.id.to_s)
+ end
+ end
+
it "renders the record it links to" do
expect(relationship_object.to_h[:data]).to eq(type: "users", id: author.id.to_s)
end
diff --git a/spec/lib/json_api_kit/document/resource_object_spec.rb b/spec/lib/json_api_kit/document/resource_object_spec.rb
index 13d09f55152..d9a2b9811ba 100644
--- a/spec/lib/json_api_kit/document/resource_object_spec.rb
+++ b/spec/lib/json_api_kit/document/resource_object_spec.rb
@@ -111,7 +111,7 @@ RSpec.describe JsonApiKit::Document::ResourceObject do
expect(JsonApiKit::Document::RelationshipObject).to have_received(:new).with(
linkage,
- urls:,
+ client:,
owner: record,
name: "user",
)
diff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
index 62ee9992d23..667d8190904 100644
--- a/spec/lib/json_api_kit/glossary/version_rule_spec.rb
+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
@@ -80,6 +80,40 @@ RSpec.describe JsonApiKit::Glossary::VersionRule do
expect(declared_attributes).to eq(name.with(value: "published_at") => "2026-08-01 00:00:00")
end
end
+
+ context "when a converter fails after an earlier merge" do
+ let(:changes) { [first_change, second_change, reuse_change] }
+ let(:first_change) { JsonApiKitSpec::MergeRuleChange.new(__FILE__) }
+ let(:second_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ resource :topics do
+ renamed_attribute from: :posted_at,
+ to: :created_at,
+ up: ->(value) { Time.iso8601(value) },
+ down: ->(value) { value.iso8601 }
+ end
+ end
+ .new(__FILE__)
+ end
+ let(:reuse_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ resource :topics do
+ renamed_attribute from: :other_date, to: :posted_at
+ end
+ end
+ .new(__FILE__)
+ end
+ let(:value) { "posted_date" }
+ let(:attributes) { { name => "invalid", name.with(value: "posted_time") => "invalid" } }
+
+ it "reports the earlier merge inputs without applying the later rename" do
+ expect { declared_attributes }.to raise_error(
+ having_attributes(names: [name, name.with(value: "posted_time")]),
+ )
+ end
+ end
end
describe "#declared_name" do
diff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rb
index 4f86f8f3dfb..3df45e30c13 100644
--- a/spec/lib/json_api_kit/glossary_spec.rb
+++ b/spec/lib/json_api_kit/glossary_spec.rb
@@ -53,7 +53,7 @@ RSpec.describe JsonApiKit::Glossary do
subject(:glossary) { described_class.new([described_class::CasingRule]) }
let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }
- let(:change) { JsonApiKitSpec::GlossaryChange.new(__FILE__) }
+ let(:version_change) { JsonApiKitSpec::GlossaryChange.new(__FILE__) }
let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
let(:value) { "createdAt" }
@@ -150,6 +150,32 @@ RSpec.describe JsonApiKit::Glossary do
end
end
+ context "when conversion fails between two rules" do
+ let(:glossary) { described_class.new([first_rule, failing_rule, last_rule]) }
+ let(:first_rule) { JsonApiKitSpec::MarkingRule.new("first") }
+ let(:last_rule) { JsonApiKitSpec::MarkingRule.new("last") }
+ let(:failing_rule) do
+ Class
+ .new do
+ def declared_name(name) = name
+
+ def declared_attributes(attributes)
+ raise JsonApiKit::VersionChange::Converter::Failure.new(attributes.keys)
+ end
+
+ def member_name(name) = name.convert { "#{it}>failure" }
+ end
+ .new
+ end
+
+ it "translates failure names through the preceding rules only" do
+ expect { declared_attributes }.to raise_error(
+ described_class::BadValue,
+ "This version cannot convert the value of createdAt<first>first.",
+ )
+ end
+ end
+
context "with several rules" do
subject(:glossary) { described_class.new([mark_a, mark_b]) }
@@ -157,7 +183,9 @@ RSpec.describe JsonApiKit::Glossary do
let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
it "applies them in order" do
- expect(declared_attributes).to eq(name.with(value: "createdAt<a<b") => "Anchors and pages")
+ expect(declared_attributes).to eq(
+ name.with(value: "createdAt<a<b", type: "topics<a<b") => "Anchors and pages",
+ )
end
end
end
@@ -165,6 +193,40 @@ RSpec.describe JsonApiKit::Glossary do
describe "#declared_name" do
subject(:declared_name) { glossary.declared_name(name) }
+ context "when a casing correction precedes a type change" do
+ let(:glossary) { described_class.resource(version) }
+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "discussions") }
+ let(:value) { "created_at" }
+ let(:version_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ renamed_type from: :discussions, to: :topics
+ resource :topics do
+ renamed_attribute from: :posted_at, to: :created_at
+ end
+ end
+ .new(__FILE__)
+ end
+
+ before { allow(JsonApiKit::VersionChange).to receive(:after).and_return([version_change]) }
+
+ it "translates the correction through the remaining rules" do
+ expect { declared_name }.to raise_error(
+ having_attributes(member: name.with(value: "postedAt")),
+ )
+ end
+
+ context "when only the casing is incorrect" do
+ let(:value) { "posted_at" }
+
+ it "still rejects the original name" do
+ expect { declared_name }.to raise_error(
+ having_attributes(member: name.with(value: "postedAt")),
+ )
+ end
+ end
+ end
+
it "returns the declared name" do
expect(declared_name).to eq(name.with(value: "created_at"))
end
@@ -213,7 +275,9 @@ RSpec.describe JsonApiKit::Glossary do
let(:value) { "postedAt" }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ [version_change],
+ )
end
it "returns the current name" do
@@ -241,7 +305,7 @@ RSpec.describe JsonApiKit::Glossary do
before do
allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
- [change, JsonApiKitSpec::GlossaryReuseChange.new(__FILE__)],
+ [version_change, JsonApiKitSpec::GlossaryReuseChange.new(__FILE__)],
)
end
@@ -258,7 +322,32 @@ RSpec.describe JsonApiKit::Glossary do
let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
it "applies them in order" do
- expect(declared_name).to eq(name.with(value: "createdAt<a<b"))
+ expect(declared_name).to eq(name.with(value: "createdAt<a<b", type: "topics<a<b"))
+ end
+ end
+ end
+
+ describe "#member_type" do
+ subject(:member_type) { glossary.member_type("discussion_threads") }
+
+ it "returns the type in camel case" do
+ expect(member_type).to eq("discussionThreads")
+ end
+
+ context "when the type has a historical name" do
+ let(:glossary) { described_class.resource(version) }
+ let(:version_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ renamed_type from: :forum_topics, to: :discussion_threads
+ end
+ .new(__FILE__)
+ end
+
+ before { allow(JsonApiKit::VersionChange).to receive(:after).and_return([version_change]) }
+
+ it "returns the historical type in camel case" do
+ expect(member_type).to eq("forumTopics")
end
end
end
@@ -293,7 +382,9 @@ RSpec.describe JsonApiKit::Glossary do
let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
it "applies them in reverse order" do
- expect(member_attributes).to eq(name.with(value: "title>b>a") => "Anchors and pages")
+ expect(member_attributes).to eq(
+ name.with(value: "title>b>a", type: "topics>b>a") => "Anchors and pages",
+ )
end
end
end
@@ -323,7 +414,9 @@ RSpec.describe JsonApiKit::Glossary do
subject(:glossary) { described_class.resource(version) }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ [version_change],
+ )
end
it "returns the name of this version, on the wire" do
@@ -338,7 +431,7 @@ RSpec.describe JsonApiKit::Glossary do
let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
it "applies them in reverse order" do
- expect(member_name).to eq(name.with(value: "created_at>b>a"))
+ expect(member_name).to eq(name.with(value: "created_at>b>a", type: "topics>b>a"))
end
end
end
diff --git a/spec/lib/json_api_kit/name/resource_scope_spec.rb b/spec/lib/json_api_kit/name/resource_scope_spec.rb
new file mode 100644
index 00000000000..1563949f3a3
--- /dev/null
+++ b/spec/lib/json_api_kit/name/resource_scope_spec.rb
@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::Name::ResourceScope do
+ [
+ JsonApiKit::Name::Field,
+ JsonApiKit::Name::Sort,
+ JsonApiKit::Name::Filter,
+ JsonApiKit::Name::Anchor,
+ JsonApiKit::Name::Relationship,
+ ].each do |kind|
+ describe kind do
+ let(:name) { kind.new(value: "posted_at", type: "discussion_threads") }
+
+ describe "#convert" do
+ subject(:conversion) { name.convert(&:upcase) }
+
+ it "converts the value and its owning type" do
+ expect(conversion).to eq(kind.new(value: "POSTED_AT", type: "DISCUSSION_THREADS"))
+ end
+ end
+
+ describe "#convert_type" do
+ subject(:conversion) { name.convert_type(&:upcase) }
+
+ it "converts only the owning type" do
+ expect(conversion).to eq(name.with(type: "DISCUSSION_THREADS"))
+ end
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/name/support.rb b/spec/lib/json_api_kit/name/support.rb
index f5bd207dd19..3d3953bf6cd 100644
--- a/spec/lib/json_api_kit/name/support.rb
+++ b/spec/lib/json_api_kit/name/support.rb
@@ -3,7 +3,7 @@
RSpec.shared_examples "a name" do
describe "#convert" do
it "returns the name with the converted value" do
- expect(name.convert(&:upcase)).to eq(name.with(value: name.value.upcase))
+ expect(name.convert(&:upcase).value).to eq(name.value.upcase)
end
end
diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rb
index a7e984bc8f6..16cda01f044 100644
--- a/spec/lib/json_api_kit/request/parameters_spec.rb
+++ b/spec/lib/json_api_kit/request/parameters_spec.rb
@@ -319,6 +319,85 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
end
+ context "when a type changes after a field name" do
+ let(:glossary) { JsonApiKit::Glossary.resource(JsonApiKit::Timeline::FIRST_RELEASE) }
+ let(:field_change) do
+ Class
+ .new(JsonApiKit::VersionChange) do
+ resource :discussion_threads do
+ renamed_attribute from: :heading, to: :title
+ renamed_filter from: :label, to: :title
+ end
+ end
+ .new(__FILE__)
+ end
+ let(:type_change) do
+ Class
+ .new(JsonApiKit::VersionChange) { renamed_type from: :discussion_threads, to: :topics }
+ .new(__FILE__)
+ end
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).and_return([field_change, type_change])
+ end
+
+ context "when the request supplies a fieldset" do
+ let(:parameters) { { "fields" => { "discussionThreads" => "heading" } } }
+
+ it "translates the type and field together" do
+ expect(declared_parameters).to eq("fields" => { "topics" => ["title"] })
+ end
+ end
+
+ context "when the fieldset is empty" do
+ let(:parameters) { { "fields" => { "discussionThreads" => "" } } }
+
+ it "translates the type without a field name" do
+ expect(declared_parameters).to eq("fields" => { "topics" => [] })
+ end
+ end
+
+ context "when the fieldset value is invalid" do
+ let(:parameters) { { "fields" => { "discussionThreads" => 42 } } }
+
+ it "translates the type for the contract" do
+ expect(declared_parameters).to eq("fields" => { "topics" => 42 })
+ end
+ end
+
+ context "when the request supplies names without a type" do
+ let(:parameters) do
+ {
+ "sort" => "heading",
+ "filter" => {
+ "label" => "A",
+ },
+ "page" => {
+ "anchor" => {
+ "heading" => "A",
+ },
+ },
+ }
+ end
+
+ it "derives the historical type before translating names" do
+ expect(declared_parameters).to eq(
+ "sort" => {
+ "title" => :asc,
+ },
+ "filter" => {
+ "title" => "A",
+ },
+ "page" => {
+ "anchor" => {
+ "title" => "A",
+ },
+ },
+ )
+ end
+ end
+ end
+
describe "#fieldsets" do
subject(:fieldsets) { request_parameters.fieldsets }
diff --git a/spec/lib/json_api_kit/version_change/converter/failure_spec.rb b/spec/lib/json_api_kit/version_change/converter/failure_spec.rb
new file mode 100644
index 00000000000..a142173ef75
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change/converter/failure_spec.rb
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChange::Converter::Failure do
+ let(:failure) { described_class.new([field]) }
+ let(:field) { JsonApiKit::Name::Field.new(value: "posted_at", type: "topics") }
+
+ describe "#convert_names" do
+ subject(:conversion_failure) { failure.convert_names { it.with(type: "discussions") } }
+
+ it "returns a failure with the translated names" do
+ expect(conversion_failure).to have_attributes(names: [field.with(type: "discussions")])
+ end
+
+ it "preserves the original failure's names" do
+ conversion_failure
+ expect(failure.names).to eq([field])
+ end
+
+ context "when a name expands into several names" do
+ subject(:conversion_failure) { failure.convert_names { previous_names } }
+
+ let(:previous_names) { [field.with(value: "posted_date"), field.with(value: "posted_time")] }
+
+ it "preserves the order of the input fields" do
+ expect(conversion_failure.names).to eq(previous_names)
+ end
+
+ it "uses the translated names in the message" do
+ expect(conversion_failure.message).to eq(
+ "cannot convert the value of posted_date, posted_time",
+ )
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/version_change/type_renames_spec.rb b/spec/lib/json_api_kit/version_change/type_renames_spec.rb
new file mode 100644
index 00000000000..dd62cc65d3b
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change/type_renames_spec.rb
@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChange do
+ subject(:version_change) { change_class.new("2026-09-02_rename_types.rb") }
+
+ let(:change_class) do
+ Class.new(described_class) do
+ version "2026-09-02"
+ description "Things become items."
+
+ resource :items do
+ merged_attributes from: %i[first last],
+ to: :name,
+ up: ->(first, last) { "#{first} #{last}" },
+ down: ->(name) { name.split(" ") }
+ end
+
+ renamed_type from: :things, to: :items
+ end
+ end
+ let(:field) { JsonApiKit::Name::Field.new(value: "first", type: "things") }
+
+ describe ".renamed_type" do
+ subject(:declare_type) { Class.new(described_class).renamed_type(**options) }
+
+ let(:options) { { from: :things, to: :items, up: ->(value) { value } } }
+
+ it "rejects an up converter" do
+ expect { declare_type }.to raise_error(ArgumentError, "unknown keyword: :up")
+ end
+
+ context "when the declaration supplies a down converter" do
+ let(:options) { { from: :things, to: :items, down: ->(value) { value } } }
+
+ it "rejects a down converter" do
+ expect { declare_type }.to raise_error(ArgumentError, "unknown keyword: :down")
+ end
+ end
+ end
+
+ describe "#verify!" do
+ subject(:verify) { version_change.verify! }
+
+ before { freeze_time(Date.new(2026, 9, 5)) }
+
+ it "accepts a type change with field changes" do
+ expect { verify }.not_to raise_error
+ end
+
+ context "when one type has two targets" do
+ before { change_class.renamed_type from: :things, to: :widgets }
+
+ it "rejects the repeated source" do
+ expect { verify }.to raise_error(ArgumentError, /changes things twice/)
+ end
+ end
+
+ context "when two types have one target" do
+ before { change_class.renamed_type from: :widgets, to: :items }
+
+ it "rejects the repeated target" do
+ expect { verify }.to raise_error(ArgumentError, /changes two names into items/)
+ end
+ end
+ end
+
+ describe "#current" do
+ subject(:current_name) { version_change.current(name) }
+
+ let(:name) { field }
+
+ it "changes the owning type before the field name" do
+ expect(current_name).to eq(field.with(value: "name", type: "items"))
+ end
+
+ context "when the name is a type" do
+ let(:name) { JsonApiKit::Name::Type.new(value: "things") }
+
+ it "changes the type value" do
+ expect(current_name).to eq(name.with(value: "items"))
+ end
+ end
+
+ context "when the name has no owning type" do
+ let(:name) { JsonApiKit::Name::Member.new(value: "things") }
+
+ it "preserves the member name" do
+ expect(current_name).to eq(name)
+ end
+ end
+
+ context "when the name belongs to another type" do
+ let(:name) { field.with(type: "people") }
+
+ it "preserves the field name" do
+ expect(current_name).to eq(name)
+ end
+ end
+
+ context "when a relationship has the same spelling as the old type" do
+ let(:name) { JsonApiKit::Name::Relationship.new(value: "things", type: "things") }
+
+ it "changes only the owning type" do
+ expect(current_name).to eq(name.with(type: "items"))
+ end
+ end
+
+ context "when a sort path contains the old type" do
+ let(:name) { JsonApiKit::Name::Sort.new(value: "things.first", type: "things") }
+
+ it "preserves the path" do
+ expect(current_name).to eq(name.with(type: "items"))
+ end
+ end
+ end
+
+ describe "#current_attributes" do
+ subject(:current_attributes) { version_change.current_attributes(attributes) }
+
+ let(:attributes) { { field.with(value: "last") => "B", field => "A" } }
+
+ it "changes the type before merging values in declaration order" do
+ expect(current_attributes).to eq(field.with(value: "name", type: "items") => "A B")
+ end
+
+ context "when a converter fails after the type changes" do
+ let(:change_class) do
+ Class.new(described_class) do
+ renamed_type from: :things, to: :items
+
+ resource :items do
+ renamed_attribute from: :former_first, to: :first
+ merged_attributes from: %i[first last],
+ to: :name,
+ up: ->(first, last) do
+ [first.fetch(:label), last.fetch(:label)].join(" ")
+ end,
+ down: ->(name) { name.split(" ").map { { label: it } } }
+ end
+ end
+ end
+
+ it "reverses the type phase without reversing the field phase" do
+ expect { current_attributes }.to raise_error(
+ having_attributes(names: [field, field.with(value: "last")]),
+ )
+ end
+ end
+ end
+
+ describe "#previous" do
+ subject(:previous_name) { version_change.previous(name) }
+
+ let(:name) { field.with(value: "name", type: "items") }
+
+ it "changes the field before its owning type" do
+ expect(previous_name).to eq(field)
+ end
+
+ context "when the name is a type" do
+ let(:name) { JsonApiKit::Name::Type.new(value: "items") }
+
+ it "reverses the type change" do
+ expect(previous_name).to eq(name.with(value: "things"))
+ end
+ end
+ end
+
+ describe "#previous_names" do
+ subject(:previous_names) do
+ version_change.previous_names(field.with(value: "name", type: "items"))
+ end
+
+ it "reverses the type change for each merge component" do
+ expect(previous_names).to eq([field, field.with(value: "last")])
+ end
+ end
+
+ describe "#previous_attributes" do
+ subject(:previous_attributes) { version_change.previous_attributes(attributes) }
+
+ let(:attributes) { { field.with(value: "name", type: "items") => "A B" } }
+
+ it "splits the value before reversing the type change" do
+ expect(previous_attributes).to eq(field => "A", field.with(value: "last") => "B")
+ end
+ end
+end