A platform for community discussion. Free, open, simple.
DEV: Convert a renamed attribute's value across JSON:API versions (#43349)
Loïc Guitautde00917e8d51
diff --git a/lib/json_api_kit/declarations/attributes.rb b/lib/json_api_kit/declarations/attributes.rbindex 79b9158acfd..1159dcc7416 100644--- a/lib/json_api_kit/declarations/attributes.rb+++ b/lib/json_api_kit/declarations/attributes.rb@@ -3,23 +3,29 @@module JsonApiKitmodule Declarationsclass Attributes- def initialize(attributes, guardian:, schema:)+ def initialize(attributes, guardian:, schema:, type:)@attributes = attributes@guardian = guardian@schema = schema+ @type = type+ @field_names = {}enddef names = attributes.map(&:name)- def values_for(record) = readable(record).to_h { [it.name, it.value_for(record)] }+ def values_for(record) = readable(record).to_h { [field_name(it), it.value_for(record)] }def columns = Columns.for(attributes.map { it.column_for(schema) })private- attr_reader :attributes, :guardian, :schema+ attr_reader :attributes, :guardian, :schema, :type, :field_namesdef readable(record) = attributes.select { it.readable_for?(guardian, record) }++ def field_name(attribute)+ field_names[attribute] ||= Name::Field.new(value: attribute.name, type:)+ endendendenddiff --git a/lib/json_api_kit/declarations/fields.rb b/lib/json_api_kit/declarations/fields.rbindex f030934de70..047d31dab38 100644--- a/lib/json_api_kit/declarations/fields.rb+++ b/lib/json_api_kit/declarations/fields.rb@@ -12,16 +12,19 @@ module JsonApiKitnew(names, **declarations)end- def initialize(names, guardian:, attributes:, relationships:, schema:)+ def initialize(names, guardian:, attributes:, relationships:, schema:, type:)@names = names@guardian = guardian@declared_attributes = attributes@declared_relationships = relationships@schema = schema+ @type = typeverify_field_namesend- def attributes = @attributes ||= Attributes.new(pick(declared_attributes), guardian:, schema:)+ def attributes+ @attributes ||= Attributes.new(pick(declared_attributes), guardian:, schema:, type:)+ enddef relationships = Relationships.new(pick(declared_relationships))@@ -29,7 +32,7 @@ module JsonApiKitprivate- attr_reader :names, :guardian, :declared_attributes, :declared_relationships, :schema+ attr_reader :names, :guardian, :declared_attributes, :declared_relationships, :schema, :typedef pick(fields) = readable(fields).select { names.include?(it.name) }diff --git a/lib/json_api_kit/document/resource_object.rb b/lib/json_api_kit/document/resource_object.rbindex 3456fa8dbf9..bab7bd87602 100644--- a/lib/json_api_kit/document/resource_object.rb+++ b/lib/json_api_kit/document/resource_object.rb@@ -18,13 +18,11 @@ module JsonApiKitattr_reader :record, :urls, :glossary, :meta- def field(value) = Name::Field.new(value:, type:)-def relationship(value) = Name::Relationship.new(value:, type:)def member_value(name) = glossary.member_name(name).value- def attributes = record.attributes.transform_keys { member_value(field(it)) }+ def attributes = glossary.member_attributes(record.attributes).transform_keys(&:value)def relationshipsrecord.relationships.to_h do |name, linkage|diff --git a/lib/json_api_kit/glossary.rb b/lib/json_api_kit/glossary.rbindex 985baf4f4c5..8549970d2f0 100644--- a/lib/json_api_kit/glossary.rb+++ b/lib/json_api_kit/glossary.rb@@ -40,6 +40,11 @@ module JsonApiKit@member_names = {}end+ def declared_attributes(attributes)+ attributes.each_key { declared_name(it) }+ rules.reduce(attributes) { |result, rule| rule.declared_attributes(result) }+ end+def declared_name(name)declared_names[name] ||= rules.reduce(name) { |result, rule| rule.declared_name(result) }rescue Correction => correction@@ -52,6 +57,10 @@ module JsonApiKit.reduce(name) { |result, rule| rule.member_name(result) }end+ def member_attributes(attributes)+ rules.reverse_each.reduce(attributes) { |result, rule| rule.member_attributes(result) }+ end+privateattr_reader :rules, :declared_names, :member_namesdiff --git a/lib/json_api_kit/glossary/casing_rule.rb b/lib/json_api_kit/glossary/casing_rule.rbindex 6c4d6a0870f..39fad511454 100644--- a/lib/json_api_kit/glossary/casing_rule.rb+++ b/lib/json_api_kit/glossary/casing_rule.rb@@ -5,21 +5,28 @@ module JsonApiKitmodule CasingRuleCAMEL_BOUNDARY = /(?<before>[a-z\d])(?<capital>[A-Z])/SNAKE_BOUNDARY = /_(?<letter>[a-z\d])/+ MEMBER_NAMES = Hash.new { |cache, name| cache[name] = camel_case(name) }class << self+ def declared_attributes(attributes) = attributes.transform_keys { declared_name(it) }+def declared_name(name)- snake_case(name).tap { raise Correction.new(it) unless member_name(it) == name }+ snake_case(name).tap { raise Correction.new(it) unless camel_case(it) == name }end- def member_name(name)- name.convert { it.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase } }- end+ def member_name(name) = camel_case(name)++ def member_attributes(attributes) = attributes.transform_keys { MEMBER_NAMES[it] }privatedef snake_case(name)name.convert { it.gsub(CAMEL_BOUNDARY, '\k<before>_\k<capital>').downcase }end++ def camel_case(name)+ name.convert { it.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase } }+ endendendenddiff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rbindex b11a4dcc8da..483301b3390 100644--- a/lib/json_api_kit/glossary/version_rule.rb+++ b/lib/json_api_kit/glossary/version_rule.rb@@ -7,6 +7,10 @@ module JsonApiKit@changes = VersionChange.after(version)end+ def declared_attributes(attributes)+ changes.reduce(attributes) { |result, change| change.current_attributes(result) }+ end+def declared_name(name)current_name(name).tap { raise Correction.new(it) unless member_name(it) == name }end@@ -15,6 +19,12 @@ module JsonApiKitchanges.reverse_each.reduce(name) { |result, change| change.previous(result) }end+ def member_attributes(attributes)+ changes+ .reverse_each+ .reduce(attributes) { |result, change| change.previous_attributes(result) }+ end+privateattr_reader :changesdiff --git a/lib/json_api_kit/name/anchor.rb b/lib/json_api_kit/name/anchor.rbindex 7ce5bbea41b..dd04223ccdb 100644--- a/lib/json_api_kit/name/anchor.rb+++ b/lib/json_api_kit/name/anchor.rb@@ -2,11 +2,6 @@module JsonApiKitmodule Name- Anchor =- Data.define(:value, :type) do- include Name-- def kind = :anchor- end+ Anchor = Data.define(:value, :type) { include Name }endenddiff --git a/lib/json_api_kit/name/field.rb b/lib/json_api_kit/name/field.rbindex b44a3e0bd62..f94eff145ad 100644--- a/lib/json_api_kit/name/field.rb+++ b/lib/json_api_kit/name/field.rb@@ -2,11 +2,6 @@module JsonApiKitmodule Name- Field =- Data.define(:value, :type) do- include Name-- def kind = :field- end+ Field = Data.define(:value, :type) { include Name }endenddiff --git a/lib/json_api_kit/name/filter.rb b/lib/json_api_kit/name/filter.rbindex 7af6576c613..95f29c8a40c 100644--- a/lib/json_api_kit/name/filter.rb+++ b/lib/json_api_kit/name/filter.rb@@ -2,11 +2,6 @@module JsonApiKitmodule Name- Filter =- Data.define(:value, :type) do- include Name-- def kind = :filter- end+ Filter = Data.define(:value, :type) { include Name }endenddiff --git a/lib/json_api_kit/name/member.rb b/lib/json_api_kit/name/member.rbindex 50b399d49ba..9ec2f33ee3e 100644--- a/lib/json_api_kit/name/member.rb+++ b/lib/json_api_kit/name/member.rb@@ -2,11 +2,6 @@module JsonApiKitmodule Name- Member =- Data.define(:value) do- include Name-- def kind = :member- end+ Member = Data.define(:value) { include Name }endenddiff --git a/lib/json_api_kit/name/relationship.rb b/lib/json_api_kit/name/relationship.rbindex 9703d8b9269..4c5c75f9c71 100644--- a/lib/json_api_kit/name/relationship.rb+++ b/lib/json_api_kit/name/relationship.rb@@ -2,11 +2,6 @@module JsonApiKitmodule Name- Relationship =- Data.define(:value, :type) do- include Name-- def kind = :relationship- end+ Relationship = Data.define(:value, :type) { include Name }endenddiff --git a/lib/json_api_kit/name/sort.rb b/lib/json_api_kit/name/sort.rbindex 9a6ea28f791..4525461b3e8 100644--- a/lib/json_api_kit/name/sort.rb+++ b/lib/json_api_kit/name/sort.rb@@ -2,11 +2,6 @@module JsonApiKitmodule Name- Sort =- Data.define(:value, :type) do- include Name-- def kind = :sort- end+ Sort = Data.define(:value, :type) { include Name }endenddiff --git a/lib/json_api_kit/query.rb b/lib/json_api_kit/query.rbindex bcc5858ecfa..1e5177512bf 100644--- a/lib/json_api_kit/query.rb+++ b/lib/json_api_kit/query.rb@@ -13,8 +13,8 @@ module JsonApiKitdef records@records ||=Records.new(- rows.map do- Record.new(it, fields, type:, namespace:, relationships: sideloads.linkage_for(it))+ rows.map do |row|+ Record.new(row, fields, type:, namespace:, relationships: sideloads.linkage_for(row))end,)enddiff --git a/lib/json_api_kit/request/contract/filtering.rb b/lib/json_api_kit/request/contract/filtering.rbindex 4c61916fcf2..5107166c9f4 100644--- a/lib/json_api_kit/request/contract/filtering.rb+++ b/lib/json_api_kit/request/contract/filtering.rb@@ -18,8 +18,8 @@ module JsonApiKitdef check_filter_namesrefuse_unknown(:filter,- (filter.keys - resource.filter_names).map do- Name::Filter.new(value: it.to_s, type: resource.type)+ (filter.keys - resource.filter_names).map do |name|+ Name::Filter.new(value: name.to_s, type: resource.type)end,)enddiff --git a/lib/json_api_kit/request/contract/paging.rb b/lib/json_api_kit/request/contract/paging.rbindex edebe2cc9bf..c000f826f30 100644--- a/lib/json_api_kit/request/contract/paging.rb+++ b/lib/json_api_kit/request/contract/paging.rb@@ -102,8 +102,8 @@ module JsonApiKitdef raw_cursors = { after:, before: }.compactdef check_cursors- (raw_cursors.keys - cursors.keys).each do- errors.add(it, :unreadable_cursor, message: "unreadable cursor")+ (raw_cursors.keys - cursors.keys).each do |name|+ errors.add(name, :unreadable_cursor, message: "unreadable cursor")endenddiff --git a/lib/json_api_kit/request/contract/sorting.rb b/lib/json_api_kit/request/contract/sorting.rbindex 24c98de4b65..37bac101a2d 100644--- a/lib/json_api_kit/request/contract/sorting.rb+++ b/lib/json_api_kit/request/contract/sorting.rb@@ -40,8 +40,8 @@ module JsonApiKitdef check_sort_namesrefuse_unknown(:sort,- (sort.keys - resource.sort_names).map do- Name::Sort.new(value: it.to_s, type: resource.type)+ (sort.keys - resource.sort_names).map do |name|+ Name::Sort.new(value: name.to_s, type: resource.type)end,)enddiff --git a/lib/json_api_kit/request/family/fields.rb b/lib/json_api_kit/request/family/fields.rbindex 8d893094eaf..519f372a8d2 100644--- a/lib/json_api_kit/request/family/fields.rb+++ b/lib/json_api_kit/request/family/fields.rb@@ -9,8 +9,8 @@ module JsonApiKitvalue.to_h do |fieldset_type, fields|[fieldset_type,- names(fields, path + [fieldset_type]) do- Name::Field.new(value: it, type: fieldset_type)+ names(fields, path + [fieldset_type]) do |field|+ Name::Field.new(value: field, type: fieldset_type)end,]enddiff --git a/lib/json_api_kit/request/family/page.rb b/lib/json_api_kit/request/family/page.rbindex 530b2da38f1..055d294455b 100644--- a/lib/json_api_kit/request/family/page.rb+++ b/lib/json_api_kit/request/family/page.rb@@ -16,7 +16,20 @@ module JsonApiKitprivate- def anchor(value, path) = names(value, path) { Name::Anchor.new(value: it, type:) }+ def anchor(value, path)+ return names(value, path) { anchor_name(it) } unless value.is_a?(Hash)+ declared_anchor(value, path)+ end++ def declared_anchor(value, path)+ glossary.declared_attributes(value.transform_keys { anchor_name(it) }).transform_keys(+ &:value+ )+ rescue Glossary::NotAMemberName => error+ raise error.at(ParameterName.new(*path, error.raw.value).to_s)+ end++ def anchor_name(value) = Name::Anchor.new(value:, type:)endendenddiff --git a/lib/json_api_kit/resource/fields.rb b/lib/json_api_kit/resource/fields.rbindex 1ce2ff8d5dd..529d2d3893b 100644--- a/lib/json_api_kit/resource/fields.rb+++ b/lib/json_api_kit/resource/fields.rb@@ -42,6 +42,7 @@ module JsonApiKitattributes: declared_attributes,relationships: declared_relationships,schema:,+ type:,)enddiff --git a/lib/json_api_kit/sideloads.rb b/lib/json_api_kit/sideloads.rbindex 31fb2765665..112fbdeece6 100644--- a/lib/json_api_kit/sideloads.rb+++ b/lib/json_api_kit/sideloads.rb@@ -4,8 +4,14 @@ module JsonApiKitclass Sideloadsdef self.for(relationships, paths:, rows:, request:, schema:)new(- relationships.map do- Sideload.new(it, paths: paths.next_for(it.name), rows:, request:, schema:)+ relationships.map do |relationship|+ Sideload.new(+ relationship,+ paths: paths.next_for(relationship.name),+ rows:,+ request:,+ schema:,+ )end,)enddiff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rbindex 06db6587afd..7e641bf2f41 100644--- a/lib/json_api_kit/version_change.rb+++ b/lib/json_api_kit/version_change.rb@@ -4,6 +4,7 @@ module JsonApiKitclass VersionChangeCHANGES_DIRECTORY = Rails.root.join("config/api_changes")DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}_/+ PASS_THROUGH = ->(_index, name) { PassThrough.new(name) }class << selfdef all = @all ||= read(CHANGES_DIRECTORY)@@ -52,6 +53,8 @@ module JsonApiKitdef initialize(source)@source = source+ @upward = index_by(&:from)+ @downward = index_by(&:to)enddef verify!@@ -61,20 +64,32 @@ module JsonApiKitraise ArgumentError, "#{source} is dated on or before the first release."endraise ArgumentError, "#{source} has no description." if description.blank?+ duplicate_name(:from).try { raise ArgumentError, "#{source} renames #{it} twice." }+ duplicate_name(:to).try { raise ArgumentError, "#{source} renames two names to #{it}." }return if File.basename(source).start_with?(version.to_s)raise ArgumentError, "The file name must start with the version #{version}: #{source}."end- def current(name)- transformations.reduce(name) { |result, transformation| transformation.current(result) }+ def current(name) = upward[name].current++ def current_attributes(attributes)+ attributes.flat_map { |name, value| upward[name].current_pairs(value) }.to_hend- def previous(name)- transformations- .reverse_each- .reduce(name) { |result, transformation| transformation.previous(result) }+ def previous(name) = downward[name].previous++ def previous_attributes(attributes)+ attributes.flat_map { |name, value| downward[name].previous_pairs(value) }.to_hend- def introduces?(name) = transformations.any? { it.introduces?(name) }+ private++ attr_reader :upward, :downward++ def index_by(&) = transformations.index_by(&).tap { it.default_proc = PASS_THROUGH }++ def duplicate_name(field)+ transformations.map(&field).tally.detect { |_name, count| count > 1 }&.first+ endendenddiff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rbindex 50aa15ea8bc..7890225a357 100644--- a/lib/json_api_kit/version_change/declarations.rb+++ b/lib/json_api_kit/version_change/declarations.rb@@ -3,16 +3,28 @@module JsonApiKitclass VersionChangeclass Declarations- DERIVED_FROM_AN_ATTRIBUTE = %i[field sort anchor].freeze+ DERIVED_FROM_AN_ATTRIBUTE = [Name::Field, Name::Sort, Name::Anchor].freeze+ NO_CONVERSION = ->(value) { value }def initialize(type)@type = type.to_s@transformations = []end- def renamed_attribute(from:, to:)- DERIVED_FROM_AN_ATTRIBUTE.each do- transformations << Rename.new(kind: it, type:, from: from.to_s, to: to.to_s)+ def renamed_attribute(from:, to:, up: NO_CONVERSION, down: NO_CONVERSION)+ if [up, down].count(NO_CONVERSION) == 1+ raise ArgumentError, "Declare both up: and down: to rename #{from} to #{to}."+ end+ unless [up, down].all? { it.respond_to?(:call) }+ raise ArgumentError, "up: and down: must respond to call, to rename #{from} to #{to}."+ end+ DERIVED_FROM_AN_ATTRIBUTE.each do |kind|+ transformations << Rename.new(+ from: kind.new(value: from.to_s, type:),+ to: kind.new(value: to.to_s, type:),+ up:,+ down:,+ )endenddiff --git a/lib/json_api_kit/version_change/pass_through.rb b/lib/json_api_kit/version_change/pass_through.rbnew file mode 100644index 00000000000..369ca575edd--- /dev/null+++ b/lib/json_api_kit/version_change/pass_through.rb@@ -0,0 +1,16 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ PassThrough =+ Data.define(:name) do+ def current = name++ def current_pairs(value) = [[name, value]]++ def previous = name++ def previous_pairs(value) = [[name, value]]+ end+ end+enddiff --git a/lib/json_api_kit/version_change/rename.rb b/lib/json_api_kit/version_change/rename.rbindex bb0749e2cf8..804f998de73 100644--- a/lib/json_api_kit/version_change/rename.rb+++ b/lib/json_api_kit/version_change/rename.rb@@ -3,22 +3,14 @@module JsonApiKitclass VersionChangeRename =- Data.define(:kind, :type, :from, :to) do- def current(name)- return name unless applies_to?(name) && name.value == from- name.with(value: to)- end+ Data.define(:from, :to, :up, :down) do+ def current = to- def previous(name)- return name unless introduces?(name)- name.with(value: from)- end+ def current_pairs(value) = [[to, up.call(value)]]- def introduces?(name) = applies_to?(name) && name.value == to+ def previous = from- private-- def applies_to?(name) = name.kind == kind && name.type == type+ def previous_pairs(value) = [[from, down.call(value)]]endendenddiff --git a/spec/fixtures/json_api_kit/api_changes_with_two_renames_from_one_name/2026-09-02_two_renames_from_one_name.rb b/spec/fixtures/json_api_kit/api_changes_with_two_renames_from_one_name/2026-09-02_two_renames_from_one_name.rbnew file mode 100644index 00000000000..16fe00746c1--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_with_two_renames_from_one_name/2026-09-02_two_renames_from_one_name.rb@@ -0,0 +1,11 @@+# frozen_string_literal: true++class TwoRenamesFromOneName < JsonApiKit::VersionChange+ version "2026-09-02"+ description "A change that renames one attribute twice."++ resource :widgets do+ renamed_attribute from: :label, to: :name+ renamed_attribute from: :label, to: :title+ end+enddiff --git a/spec/fixtures/json_api_kit/api_changes_with_two_renames_to_one_name/2026-09-02_two_renames_to_one_name.rb b/spec/fixtures/json_api_kit/api_changes_with_two_renames_to_one_name/2026-09-02_two_renames_to_one_name.rbnew file mode 100644index 00000000000..348d37e7fc0--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_with_two_renames_to_one_name/2026-09-02_two_renames_to_one_name.rb@@ -0,0 +1,11 @@+# frozen_string_literal: true++class TwoRenamesToOneName < JsonApiKit::VersionChange+ version "2026-09-02"+ description "A change that renames two attributes to one name."++ resource :widgets do+ renamed_attribute from: :label, to: :title+ renamed_attribute from: :caption, to: :title+ end+enddiff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rbindex 5c00ea5f1ee..a4b20e61f28 100644--- a/spec/integration/json_api_kit/version_changes_spec.rb+++ b/spec/integration/json_api_kit/version_changes_spec.rb@@ -13,6 +13,10 @@ module JsonApiKitSpecresource :topics dorenamed_attribute from: :posted_at, to: :created_at+ renamed_attribute from: :words,+ to: :title,+ down: ->(title) { title.to_s.split(" ") },+ up: ->(words) { words.to_a.join(" ") }endendend@@ -48,7 +52,27 @@ RSpec.describe "JSON:API version changes", type: :request doendit "sends the attributes under the names of that version" do- expect(attributes.keys).to contain_exactly("title", "postedAt")+ expect(attributes.keys).to contain_exactly("words", "postedAt")+ end++ it "sends a reshaped attribute in the shape of that version" do+ expect(attributes["words"]).to eq(%w[Bands of a segmented listing])+ end++ context "when the request selects the reshaped field" do+ let(:query) { { "fields" => { "topics" => "words" } } }++ it "sends that field only" do+ expect(attributes.keys).to contain_exactly("words")+ end+ end++ context "when the request sorts by the reshaped field" do+ let(:query) { { "sort" => "words" } }++ it "orders the rows by that attribute" do+ expect(ids).to eq([oldest.id.to_s, newest.id.to_s, middle.id.to_s])+ endendcontext "when the request selects the renamed field" do@@ -86,10 +110,29 @@ RSpec.describe "JSON:API version changes", type: :request doendend+ context "when the request anchors a window on the reshaped field" do+ let(:query) do+ {+ "sort" => "words",+ "page" => {+ "anchor" => {+ "words" => %w[Bands of a segmented listing],+ },+ "beforeSize" => "1",+ "afterSize" => "0",+ },+ }+ end++ it "sends the rows of the window" do+ expect(ids).to eq([oldest.id.to_s, newest.id.to_s])+ end+ end+context "when a refusal includes the renamed field" dolet(:query) do{- "sort" => "title",+ "sort" => "words","page" => {"anchor" => {"postedAt" => middle.created_at.iso8601(6),@@ -102,7 +145,7 @@ RSpec.describe "JSON:API version changes", type: :request doexpect(error).to eq(refusal(title: "Anchor does not match the sort",- detail: "The anchor is postedAt, but this request sorts by title.",+ detail: "The anchor is postedAt, but this request sorts by words.",parameter: "page[anchor][postedAt]",).deep_stringify_keys,)@@ -134,7 +177,7 @@ RSpec.describe "JSON:API version changes", type: :request doendit "sends the attributes under the names of the first version" do- expect(attributes.keys).to contain_exactly("title", "postedAt")+ expect(attributes.keys).to contain_exactly("words", "postedAt")endenddiff --git a/spec/lib/json_api_kit/declarations/attributes_spec.rb b/spec/lib/json_api_kit/declarations/attributes_spec.rbindex 82da7b9ee7f..f03472b196b 100644--- a/spec/lib/json_api_kit/declarations/attributes_spec.rb+++ b/spec/lib/json_api_kit/declarations/attributes_spec.rb@@ -1,7 +1,7 @@# frozen_string_literal: trueRSpec.describe JsonApiKit::Declarations::Attributes do- subject(:attributes) { described_class.new(declarations, guardian:, schema:) }+ subject(:attributes) { described_class.new(declarations, guardian:, schema:, type: "topics") }fab!(:topic) { Fabricate(:topic, title: "A field rendered from a record", closed: false) }@@ -9,6 +9,8 @@ RSpec.describe JsonApiKit::Declarations::Attributes dolet(:schema) { JsonApiKit::Schema.new(Topic) }let(:attribute) { JsonApiKit::Declarations::Attribute }let(:declarations) { [attribute.new(:title), attribute.new(:closed)] }+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }+ let(:closed) { JsonApiKit::Name::Field.new(value: "closed", type: "topics") }describe "#columns" dosubject(:columns) { attributes.columns }@@ -29,8 +31,16 @@ RSpec.describe JsonApiKit::Declarations::Attributes dodescribe "#values_for" dosubject(:attribute_values) { attributes.values_for(topic) }- it "returns the value of every field it holds" do- expect(attribute_values).to eq("title" => topic.title, "closed" => false)+ it "returns the value of every field it holds, under its name" do+ expect(attribute_values).to eq(title => topic.title, closed => false)+ end++ context "with a second record" do+ fab!(:other_topic) { Fabricate(:topic, title: "Another field rendered from a record") }++ it "builds the name of a field once" do+ expect(attribute_values.keys.first).to equal(attributes.values_for(other_topic).keys.first)+ endendcontext "when it holds no field" dodiff --git a/spec/lib/json_api_kit/declarations/fields_spec.rb b/spec/lib/json_api_kit/declarations/fields_spec.rbindex 2ce5a70d8b1..217250e36e4 100644--- a/spec/lib/json_api_kit/declarations/fields_spec.rb+++ b/spec/lib/json_api_kit/declarations/fields_spec.rb@@ -1,7 +1,9 @@# frozen_string_literal: trueRSpec.describe JsonApiKit::Declarations::Fields do- subject(:fields) { described_class.for(names, guardian:, attributes:, relationships:, schema:) }+ subject(:fields) do+ described_class.for(names, guardian:, attributes:, relationships:, schema:, type: "topics")+ endlet(:guardian) { Guardian.new }@@ -26,7 +28,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do[JsonApiKit::Declarations::Relationship::ToOne.new(:title, resource: users_resource)]end- it "refuses the declaration" do+ it "raises a collision" doexpect { fields }.to raise_error(described_class::Collision, /title/)endend@@ -39,7 +41,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do]end- it "refuses the declaration" do+ it "raises a collision" doexpect { fields }.to raise_error(described_class::Collision, /title/)endend@@ -52,24 +54,24 @@ RSpec.describe JsonApiKit::Declarations::Fields do]end- it "refuses the declaration" do+ it "raises a collision" doexpect { fields }.to raise_error(described_class::Collision, /id, type/)endendenddescribe "#attributes" do- subject(:attribute_values) { fields.attributes.values_for(topic) }+ subject(:attribute_names) { fields.attributes.values_for(topic).keys.map(&:value) }it "holds every field the resource declares" do- expect(attribute_values.keys).to eq(%w[title closed])+ expect(attribute_names).to eq(%w[title closed])endcontext "when the fieldset holds one field" dolet(:names) { %w[title] }it "holds only those" do- expect(attribute_values.keys).to eq(%w[title])+ expect(attribute_names).to eq(%w[title])endend@@ -77,7 +79,7 @@ RSpec.describe JsonApiKit::Declarations::Fields dolet(:names) { %w[closed title] }it "holds them in the order the resource declares" do- expect(attribute_values.keys).to eq(%w[title closed])+ expect(attribute_names).to eq(%w[title closed])endend@@ -85,7 +87,7 @@ RSpec.describe JsonApiKit::Declarations::Fields dolet(:names) { %w[title secrets] }it "leaves that name out" do- expect(attribute_values.keys).to eq(%w[title])+ expect(attribute_names).to eq(%w[title])endend@@ -93,7 +95,7 @@ RSpec.describe JsonApiKit::Declarations::Fields dolet(:names) { [] }it "holds no field" do- expect(attribute_values).to be_empty+ expect(attribute_names).to be_emptyendendenddiff --git a/spec/lib/json_api_kit/document/contents_spec.rb b/spec/lib/json_api_kit/document/contents_spec.rbindex 7ff1ab81d0e..b3455e6efb0 100644--- a/spec/lib/json_api_kit/document/contents_spec.rb+++ b/spec/lib/json_api_kit/document/contents_spec.rb@@ -12,7 +12,6 @@ RSpec.describe JsonApiKit::Document::Contents dolet(:other_topic_record) { record_of(other_topic, "topics") }let(:records) { [record_of(topic, "topics", "user" => linkage(author_record))] }let(:related_records) { [author_record] }-let(:guardian) { Guardian.new }def record_of(model, type, relationships = {})@@ -24,6 +23,7 @@ RSpec.describe JsonApiKit::Document::Contents doattributes: [],relationships: [],schema: JsonApiKit::Schema.new(model.class),+ type:,),type:,relationships:,@@ -37,7 +37,7 @@ RSpec.describe JsonApiKit::Document::Contents doexpect(contents.primary.map(&:record)).to eq([topic])end- context "when a path reads a primary record a second time" do+ context "when a path holds a primary record a second time" dolet(:related_records) { [author_record, record_of(topic, "topics", "tags" => linkage)] }it "holds the relationships of both readings" do@@ -59,7 +59,7 @@ RSpec.describe JsonApiKit::Document::Contents doexpect(contents.related.map(&:record)).to eq([author])end- context "when a path reads a primary record a second time" do+ context "when a path holds a primary record a second time" dolet(:related_records) { [author_record, record_of(topic, "topics")] }it "drops that record" do@@ -84,7 +84,7 @@ RSpec.describe JsonApiKit::Document::Contents doendend- context "when two paths read one record" do+ context "when two paths hold one record" dolet(:related_records) do[author_record, record_of(author, "users", "groups" => linkage(record_of(group, "groups")))]enddiff --git a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb b/spec/lib/json_api_kit/glossary/casing_rule_spec.rbindex 9e858cc031a..a2de4fd0020 100644--- a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb+++ b/spec/lib/json_api_kit/glossary/casing_rule_spec.rb@@ -5,6 +5,20 @@ RSpec.describe JsonApiKit::Glossary::CasingRule dolet(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }let(:value) { "createdAt" }+ describe "#declared_attributes" do+ subject(:declared_attributes) { rule.declared_attributes(name => "2026-08-01") }++ it "returns the attributes with their names in snake case" do+ expect(declared_attributes).to eq(name.with(value: "created_at") => "2026-08-01")+ end++ context "when a name has an underscore" do+ let(:value) { "created_at" }++ it { expect { declared_attributes }.to raise_error(JsonApiKit::Glossary::Correction) }+ end+ end+describe "#declared_name" dosubject(:declared_name) { rule.declared_name(name) }@@ -57,6 +71,29 @@ RSpec.describe JsonApiKit::Glossary::CasingRule doexpect { declared_name }.to raise_error(having_attributes(name:))endend++ context "when the name comes from a client" do+ let(:value) { "sentByClient" }++ it "adds nothing to the memo" do+ expect { declared_name }.not_to change(described_class::MEMBER_NAMES, :size)+ end+ end+ end++ describe "#member_attributes" do+ subject(:member_attributes) { rule.member_attributes(attributes) }++ let(:attributes) { { name => "2026-08-01" } }+ let(:value) { "created_at" }++ it "returns the attributes with their names in camel case" do+ expect(member_attributes).to eq(name.with(value: "createdAt") => "2026-08-01")+ end++ it "returns the same object for a name it converted before" do+ expect(member_attributes.keys.first).to equal(rule.member_attributes(attributes).keys.first)+ endenddescribe "#member_name" do@@ -83,5 +120,13 @@ RSpec.describe JsonApiKit::Glossary::CasingRule doexpect(member_name).to eq(name)endend++ context "when the name comes from a client" do+ let(:value) { "named_by_client" }++ it "adds nothing to the memo" do+ expect { member_name }.not_to change(described_class::MEMBER_NAMES, :size)+ end+ endendenddiff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rbindex b3e9a53b532..60c6431fb57 100644--- a/spec/lib/json_api_kit/glossary/version_rule_spec.rb+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb@@ -53,6 +53,14 @@ RSpec.describe JsonApiKit::Glossary::VersionRule do)end+ describe "#declared_attributes" do+ subject(:declared_attributes) { rule.declared_attributes(name => "2026-08-01") }++ it "returns the attributes with their current names" do+ expect(declared_attributes).to eq(name.with(value: "published_at") => "2026-08-01")+ end+ end+describe "#declared_name" dosubject(:declared_name) { rule.declared_name(name) }@@ -65,7 +73,7 @@ RSpec.describe JsonApiKit::Glossary::VersionRule dolet(:second_change) { JsonApiKitSpec::LabelToNameChange.new(__FILE__) }let(:value) { "name" }- it "returns the current name of the old name" do+ it "returns the current name" doexpect(declared_name).to eq(name.with(value: "title"))end@@ -97,6 +105,16 @@ RSpec.describe JsonApiKit::Glossary::VersionRule doendend+ describe "#member_attributes" do+ subject(:member_attributes) { rule.member_attributes(name => "2026-08-01") }++ let(:value) { "published_at" }++ it "returns the attributes with the names of this version" do+ expect(member_attributes).to eq(name.with(value: "posted_at") => "2026-08-01")+ end+ end+describe "#member_name" dosubject(:member_name) { rule.member_name(name) }diff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rbindex 52610724c62..4407d61444c 100644--- a/spec/lib/json_api_kit/glossary_spec.rb+++ b/spec/lib/json_api_kit/glossary_spec.rb@@ -6,6 +6,10 @@ module JsonApiKitSpecdef declared_name(name) = name.convert { "#{it}<#{mark}" }def member_name(name) = name.convert { "#{it}>#{mark}" }++ def declared_attributes(attributes) = attributes.transform_keys { declared_name(it) }++ def member_attributes(attributes) = attributes.transform_keys { member_name(it) }endclass GlossaryChange < JsonApiKit::VersionChange@@ -17,6 +21,18 @@ module JsonApiKitSpecendend+ class GlossaryShapeChange < JsonApiKit::VersionChange+ version "2026-09-15"+ description "The `words` attribute of the topics resource becomes `title`, a string."++ resource :topics do+ renamed_attribute from: :words,+ to: :title,+ down: ->(title) { title.to_s.split(" ") },+ up: ->(words) { words.to_a.join(" ") }+ end+ end+class GlossaryReuseChange < JsonApiKit::VersionChangeversion "2026-10-01"description "The `label` attribute of the topics resource is renamed to `posted_at`."@@ -67,6 +83,60 @@ RSpec.describe JsonApiKit::Glossary doendend+ describe "#declared_attributes" do+ subject(:declared_attributes) { glossary.declared_attributes(attributes) }++ let(:attributes) { { name => "Anchors and pages" } }++ it "returns the attributes with their declared names" do+ expect(declared_attributes).to eq(name.with(value: "created_at") => "Anchors and pages")+ end++ context "when a name is not a member name" do+ let(:value) { "created_at" }++ it "raises with the member name to use" do+ expect { declared_attributes }.to raise_error(/Use createdAt, not created_at\./)+ end+ end++ context "with a version rule" do+ subject(:glossary) { described_class.resource(version) }++ let(:attributes) { { name => %w[Anchors and pages] } }+ let(:value) { "words" }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(+ [JsonApiKitSpec::GlossaryShapeChange.new(__FILE__)],+ )+ end++ it "returns the attributes with the current names and shapes" do+ expect(declared_attributes).to eq(name.with(value: "title") => "Anchors and pages")+ end++ context "when a name belongs to a later version" do+ let(:value) { "title" }++ it "raises with the name of this version" do+ expect { declared_attributes }.to raise_error(/Use words, not title\./)+ end+ end+ end++ context "with several rules" do+ subject(:glossary) { described_class.new([mark_a, mark_b]) }++ let(:mark_a) { JsonApiKitSpec::MarkingRule.new("a") }+ 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")+ end+ end+ end+describe "#declared_name" dosubject(:declared_name) { glossary.declared_name(name) }@@ -150,7 +220,7 @@ RSpec.describe JsonApiKit::Glossary do)end- it "suggests the name of this version, converted once" do+ it "suggests the name of this version, on the wire" doexpect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)endend@@ -168,6 +238,41 @@ RSpec.describe JsonApiKit::Glossary doendend+ describe "#member_attributes" do+ subject(:member_attributes) { glossary.member_attributes(name => "Anchors and pages") }++ let(:value) { "title" }++ it "returns the attributes with their member names" do+ expect(member_attributes).to eq(name => "Anchors and pages")+ end++ context "with a version rule" do+ subject(:glossary) { described_class.resource(version) }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(+ [JsonApiKitSpec::GlossaryShapeChange.new(__FILE__)],+ )+ end++ it "returns the attributes with the names and the values of this version, on the wire" do+ expect(member_attributes).to eq(name.with(value: "words") => %w[Anchors and pages])+ end+ end++ context "with several rules" do+ subject(:glossary) { described_class.new([mark_a, mark_b]) }++ let(:mark_a) { JsonApiKitSpec::MarkingRule.new("a") }+ 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")+ end+ end+ end+describe "#member_name" dosubject(:member_name) { glossary.member_name(name) }diff --git a/spec/lib/json_api_kit/included_spec.rb b/spec/lib/json_api_kit/included_spec.rbindex 54005af4bea..03953e468d8 100644--- a/spec/lib/json_api_kit/included_spec.rb+++ b/spec/lib/json_api_kit/included_spec.rb@@ -10,7 +10,6 @@ RSpec.describe JsonApiKit::Included dolet(:author_record) { record_of(author, "users") }let(:records) { [record_of(topic, "topics", "user" => linkage(author_record))] }-let(:guardian) { Guardian.new }def record_of(model, type, relationships = {})@@ -22,6 +21,7 @@ RSpec.describe JsonApiKit::Included doattributes: [],relationships: [],schema: JsonApiKit::Schema.new(model.class),+ type:,),type:,relationships:,diff --git a/spec/lib/json_api_kit/name/anchor_spec.rb b/spec/lib/json_api_kit/name/anchor_spec.rbindex c39281f6399..e53299e1125 100644--- a/spec/lib/json_api_kit/name/anchor_spec.rb+++ b/spec/lib/json_api_kit/name/anchor_spec.rb@@ -5,5 +5,5 @@ require_relative "support"RSpec.describe JsonApiKit::Name::Anchor dosubject(:name) { described_class.new(value: "posted_at", type: "topics") }- it_behaves_like "a name", :anchor+ it_behaves_like "a name"enddiff --git a/spec/lib/json_api_kit/name/field_spec.rb b/spec/lib/json_api_kit/name/field_spec.rbindex e3b30d135a7..0d6527499c1 100644--- a/spec/lib/json_api_kit/name/field_spec.rb+++ b/spec/lib/json_api_kit/name/field_spec.rb@@ -5,5 +5,5 @@ require_relative "support"RSpec.describe JsonApiKit::Name::Field dosubject(:name) { described_class.new(value: "posted_at", type: "topics") }- it_behaves_like "a name", :field+ it_behaves_like "a name"enddiff --git a/spec/lib/json_api_kit/name/filter_spec.rb b/spec/lib/json_api_kit/name/filter_spec.rbindex ac22a60d0f5..e65a75fb3c3 100644--- a/spec/lib/json_api_kit/name/filter_spec.rb+++ b/spec/lib/json_api_kit/name/filter_spec.rb@@ -5,5 +5,5 @@ require_relative "support"RSpec.describe JsonApiKit::Name::Filter dosubject(:name) { described_class.new(value: "posted_at", type: "topics") }- it_behaves_like "a name", :filter+ it_behaves_like "a name"enddiff --git a/spec/lib/json_api_kit/name/member_spec.rb b/spec/lib/json_api_kit/name/member_spec.rbindex 1ca32cff057..930d8eb0989 100644--- a/spec/lib/json_api_kit/name/member_spec.rb+++ b/spec/lib/json_api_kit/name/member_spec.rb@@ -5,5 +5,5 @@ require_relative "support"RSpec.describe JsonApiKit::Name::Member dosubject(:name) { described_class.new(value: "after_size") }- it_behaves_like "a name", :member+ it_behaves_like "a name"enddiff --git a/spec/lib/json_api_kit/name/relationship_spec.rb b/spec/lib/json_api_kit/name/relationship_spec.rbindex 8d41e7517ed..bddee583ce3 100644--- a/spec/lib/json_api_kit/name/relationship_spec.rb+++ b/spec/lib/json_api_kit/name/relationship_spec.rb@@ -5,5 +5,5 @@ require_relative "support"RSpec.describe JsonApiKit::Name::Relationship dosubject(:name) { described_class.new(value: "posted_at", type: "topics") }- it_behaves_like "a name", :relationship+ it_behaves_like "a name"enddiff --git a/spec/lib/json_api_kit/name/sort_spec.rb b/spec/lib/json_api_kit/name/sort_spec.rbindex 79ec71ca4cc..a8f4b6091b2 100644--- a/spec/lib/json_api_kit/name/sort_spec.rb+++ b/spec/lib/json_api_kit/name/sort_spec.rb@@ -5,5 +5,5 @@ require_relative "support"RSpec.describe JsonApiKit::Name::Sort dosubject(:name) { described_class.new(value: "posted_at", type: "topics") }- it_behaves_like "a name", :sort+ it_behaves_like "a name"enddiff --git a/spec/lib/json_api_kit/name/support.rb b/spec/lib/json_api_kit/name/support.rbindex 5148140a637..f5bd207dd19 100644--- a/spec/lib/json_api_kit/name/support.rb+++ b/spec/lib/json_api_kit/name/support.rb@@ -1,12 +1,6 @@# frozen_string_literal: true-RSpec.shared_examples "a name" do |kind|- describe "#kind" do- it "returns #{kind.inspect}" do- expect(name.kind).to eq(kind)- end- end-+RSpec.shared_examples "a name" dodescribe "#convert" doit "returns the name with the converted value" doexpect(name.convert(&:upcase)).to eq(name.with(value: name.value.upcase))diff --git a/spec/lib/json_api_kit/query/collection_spec.rb b/spec/lib/json_api_kit/query/collection_spec.rbindex e702ceefcce..cbb290ee306 100644--- a/spec/lib/json_api_kit/query/collection_spec.rb+++ b/spec/lib/json_api_kit/query/collection_spec.rb@@ -31,7 +31,7 @@ RSpec.describe JsonApiKit::Query::Collection dodescribe ".new" dolet(:params) { { sort: { secrets: :asc } } }- it "reads nothing before a caller asks for records" do+ it "queries nothing before a caller asks for records" doexpect { query }.not_to raise_errorendend@@ -86,11 +86,11 @@ RSpec.describe JsonApiKit::Query::Collection doexpect(previous_cursor).to be_nilend- context "when a caller reads from further into the listing" do+ context "when a caller starts further into the listing" dolet(:first_cursor) { described_class.new(resource, request_for({})).rows.first.cursor.to_s }let(:params) { { page: { size: 2, after: first_cursor } } }- it "returns the cursor that reads the page before it" do+ it "returns the cursor of the page before it" doexpect(previous_cursor).to be_presentendend@@ -109,9 +109,10 @@ RSpec.describe JsonApiKit::Query::Collection doattribute :closedendend+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }- it "renders every row in the order the listing reads them" do- expect(fields.map { it["title"] }).to eq(+ it "renders every row in the order of the listing" do+ expect(fields.map { it[title] }).to eq([first_topic.title, second_topic.title, third_topic.title],)end@@ -120,10 +121,10 @@ RSpec.describe JsonApiKit::Query::Collection dolet(:params) { { fields: { topics: %w[title] } } }it "renders only those fields" do- expect(fields.first.keys).to contain_exactly("title")+ expect(fields.first.keys).to contain_exactly(title)end- it "reads only the columns those fields and the order need" do+ it "selects only the columns those fields and the order need" doexpect(query.records.first.record.attributes.keys).to contain_exactly("id","title",@@ -145,7 +146,7 @@ RSpec.describe JsonApiKit::Query::Collection doendlet(:params) { { fields: { topics: %w[title slug] } } }- it "reads the whole row" do+ it "selects every column" doexpect(query.records.first.record.attributes.keys).to include("closed", "views")endend@@ -154,22 +155,22 @@ RSpec.describe JsonApiKit::Query::Collection dodescribe "#records" dosubject(:records) { query.records.map(&:record) }- it "reads the rows the resource exposes in the order it declares" do+ it "returns the rows the resource exposes in the order it declares" doexpect(records).to eq([first_topic, second_topic, third_topic])endcontext "when the sort holds a key" dolet(:params) { { sort: { created_at: :desc } } }- it "reads the rows that way" do+ it "returns the rows in that order" doexpect(records).to eq([third_topic, second_topic, first_topic])endend- context "when the resource is read as part of another listing" do+ context "when another listing scopes the resource" dolet(:scoped_to) { Topic.where(id: [first_topic.id, third_topic.id]) }- it "reads only the rows both allow" do+ it "returns only the rows both allow" doexpect(records).to eq([first_topic, third_topic])endend@@ -177,7 +178,7 @@ RSpec.describe JsonApiKit::Query::Collection docontext "when the page holds a size" dolet(:params) { { page: { size: 2 } } }- it "reads only that many rows" do+ it "returns only that many rows" doexpect(records).to eq([first_topic, second_topic])endend@@ -186,7 +187,7 @@ RSpec.describe JsonApiKit::Query::Collection dolet(:resource) { Class.new(super()) { filter :title } }let(:params) { { filter: { title: second_topic.title } } }- it "reads only the rows that filter keeps" do+ it "returns only the rows that filter keeps" doexpect(records).to eq([second_topic])endend@@ -197,7 +198,7 @@ RSpec.describe JsonApiKit::Query::Collection doendlet(:guardian) { Guardian.new(second_topic.user) }- it "reads only the rows that scope exposes" do+ it "returns only the rows that scope exposes" doexpect(records).to eq([second_topic])endenddiff --git a/spec/lib/json_api_kit/query/individual_spec.rb b/spec/lib/json_api_kit/query/individual_spec.rbindex 79d16d3235f..5ffd9540faf 100644--- a/spec/lib/json_api_kit/query/individual_spec.rb+++ b/spec/lib/json_api_kit/query/individual_spec.rb@@ -16,6 +16,7 @@ RSpec.describe JsonApiKit::Query::Individual dolet(:request) { JsonApiKit::Request::Individual.new(params, guardian:) }let(:params) { { id: topic.id } }let(:guardian) { Guardian.new }+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }describe "#record" doit "returns the record with that id" do@@ -23,13 +24,13 @@ RSpec.describe JsonApiKit::Query::Individual doendit "renders it with the fields the resource declares" do- expect(reading.record.attributes).to eq("title" => topic.title)+ expect(reading.record.attributes).to eq(title => topic.title)endcontext "when nothing is there under that id" dolet(:params) { { id: -1 } }- it "refuses the request instead of answering with nothing" do+ it "raises not found instead of answering with nothing" doexpect { reading.record }.to raise_error(JsonApiKit::NotFound)endend@@ -37,7 +38,7 @@ RSpec.describe JsonApiKit::Query::Individual docontext "when the scope withholds the row" dolet(:resource) { Class.new(super()) { scope { Topic.where(closed: true) } } }- it "refuses the request instead of answering with nothing" do+ it "raises not found instead of answering with nothing" doexpect { reading.record }.to raise_error(JsonApiKit::NotFound)endenddiff --git a/spec/lib/json_api_kit/record_spec.rb b/spec/lib/json_api_kit/record_spec.rbindex 552b53c8fdc..5684370a3cf 100644--- a/spec/lib/json_api_kit/record_spec.rb+++ b/spec/lib/json_api_kit/record_spec.rb@@ -33,10 +33,11 @@ RSpec.describe JsonApiKit::Record doendlet(:relationships) { {} }let(:namespace) { nil }+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }describe "#attributes" doit "renders the fields that the resource declares" do- expect(record.attributes).to eq("title" => topic.title)+ expect(record.attributes).to eq(title => topic.title)endend@@ -98,7 +99,7 @@ RSpec.describe JsonApiKit::Record doendit "renders its own fields" do- expect(merged.attributes).to eq("title" => topic.title)+ expect(merged.attributes).to eq(title => topic.title)endit "leaves this record unchanged" dodiff --git a/spec/lib/json_api_kit/request/contract/collection_spec.rb b/spec/lib/json_api_kit/request/contract/collection_spec.rbindex 697dead9842..4a6a33595c6 100644--- a/spec/lib/json_api_kit/request/contract/collection_spec.rb+++ b/spec/lib/json_api_kit/request/contract/collection_spec.rb@@ -39,7 +39,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model docontext "when a parameter is unknown" dolet(:params) { { sorts: { created_at: :asc } } }- it "refuses the parameter" do+ it "adds an error on the parameter" doexpect(contract).to be_invalidexpect(contract.errors).to include(:sorts)end@@ -48,7 +48,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model docontext "when a page parameter is unknown" dolet(:params) { { page: { sise: 2 } } }- it "refuses it under the parameter it came in" do+ it "adds an error under the parameter it came in" doexpect(contract).to be_invalidexpect(contract.errors).to include(:"page.sise")end@@ -88,7 +88,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model doexpect(contract.sort).to eq("created_at" => :desc, "title" => :asc)end- context "when there’s a hyphen in the sort name" do+ context "when the sort name has a hyphen" dolet(:params) { { sort: "last-posted-at" } }it "converts it as a hash" do@@ -96,7 +96,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model doendend- context "when there’s also a cursor" do+ context "when a cursor comes with the sort" dolet(:params) { { sort: "title", page: { after: cursor } } }it "checks the cursor against that sort" do@@ -158,7 +158,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model doendend- context "when fieldset is a list of symbols" do+ context "when fieldset is a list of symbols" dolet(:params) { { fields: { topics: %i[title] } } }it "converts it as a list of fields" do@@ -174,6 +174,12 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model dobefore { contract.valid? }+ it { is_expected.to validate_length_of(:anchor).as_array.is_equal_to(1).allow_nil }+ it { is_expected.to allow_value({ id: 12 }, :first_unread).for(:anchor) }+ it { is_expected.not_to allow_value({}, { id: 12, title: "a topic" }).for(:anchor) }+ it { is_expected.not_to allow_value({ id: { a: 1 } }, { id: %w[a b] }).for(:anchor) }+ it { is_expected.not_to allow_value({ secrets: 12 }, :guesswork).for(:anchor) }+context "when the anchor is not the sort" dolet(:params) { { sort: { created_at: :asc }, page: { anchor: { title: "A" } } } }@@ -185,12 +191,6 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model doendend- it { is_expected.to validate_length_of(:anchor).as_array.is_equal_to(1).allow_nil }- it { is_expected.to allow_value({ id: 12 }, :first_unread).for(:anchor) }- it { is_expected.not_to allow_value({}, { id: 12, title: "a topic" }).for(:anchor) }- it { is_expected.not_to allow_value({ id: { a: 1 } }, { id: %w[a b] }).for(:anchor) }- it { is_expected.not_to allow_value({ secrets: 12 }, :guesswork).for(:anchor) }-context "when the anchor name matches the sort" dolet(:params) { { sort: { title: :asc }, page: {} } }@@ -315,7 +315,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model doit { is_expected.not_to allow_value("").for(:before_size) }it { is_expected.not_to allow_value("").for(:after_size) }- context "when both `page[before_size]` and `page[after_size]` are provided" do+ context "when the page holds both sizes" dolet(:params) { { page: { anchor: { id: 12 }, before_size: 25 } } }it { is_expected.to allow_value(20).for(:after_size).against(:window_size) }diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rbindex 8c24a2bee96..4e60e3225d0 100644--- a/spec/lib/json_api_kit/request/parameters_spec.rb+++ b/spec/lib/json_api_kit/request/parameters_spec.rb@@ -17,6 +17,18 @@ module JsonApiKitSpecrenamed_attribute from: :handle, to: :usernameendend++ class ParametersShapeChange < JsonApiKit::VersionChange+ version "2026-09-15"+ description "The `words` attribute of the topics resource becomes `title`, one string."++ resource :topics do+ renamed_attribute from: :words,+ to: :title,+ down: ->(title) { title.to_s.split(" ") },+ up: ->(words) { words.to_a.join(" ") }+ end+ endendRSpec.describe JsonApiKit::Request::Parameters do@@ -153,6 +165,21 @@ RSpec.describe JsonApiKit::Request::Parameters doendend+ context "when the anchor has a reshaped field" do+ let(:change) { JsonApiKitSpec::ParametersShapeChange.new(__FILE__) }+ let(:parameters) { { "page" => { "anchor" => { "words" => %w[Anchors and pages] } } } }++ it "converts the field to its current name and shape" do+ expect(declared_parameters).to eq(+ "page" => {+ "anchor" => {+ "title" => "Anchors and pages",+ },+ },+ )+ end+ end+context "when a filter has the name of a renamed field" dolet(:parameters) { { "filter" => { "postedAt" => "2026-08-01" } } }diff --git a/spec/lib/json_api_kit/resource_spec.rb b/spec/lib/json_api_kit/resource_spec.rbindex 4f775e790a9..d87a8868879 100644--- a/spec/lib/json_api_kit/resource_spec.rb+++ b/spec/lib/json_api_kit/resource_spec.rb@@ -126,7 +126,7 @@ RSpec.describe JsonApiKit::Resource docontext "when that name matches no model" dosubject(:resource) { Class.new(described_class) { model :nowhere_to_be_found } }- it "refuses the model name" do+ it "raises a missing declaration with that name" doexpect { model }.to raise_error(described_class::MissingDeclaration, /NowhereToBeFound/)endend@@ -280,12 +280,12 @@ RSpec.describe JsonApiKit::Resource doenddescribe ".default_sort" do- it "reads a listing in the order the resource declares" do+ it "orders a listing as the resource declares" doexpect(topic_resource.order.leading.name).to eq(:last_posted_at)endcontext "when the resource declares no such sort" do- it "refuses the declaration" do+ it "raises an undeclared default" doexpect {Class.new(described_class) domodel Topic@@ -334,7 +334,9 @@ RSpec.describe JsonApiKit::Resource dofab!(:topic) { Fabricate(:topic, title: "A field a resource renders") }it "renders the field the resource declares" do- expect(attribute_values).to eq("title" => topic.title)+ expect(attribute_values).to eq(+ JsonApiKit::Name::Field.new(value: "title", type: topic_resource.type) => topic.title,+ )endcontext "when the resource declares one more after a reading" do@@ -344,7 +346,9 @@ RSpec.describe JsonApiKit::Resource doendit "renders the new field too" do- expect(attribute_values).to include("closed")+ expect(attribute_values).to include(+ JsonApiKit::Name::Field.new(value: "closed", type: topic_resource.type),+ )endendend@@ -430,14 +434,14 @@ RSpec.describe JsonApiKit::Resource dodescribe ".includes" dosubject(:allowed_paths) { topic_resource.allow(JsonApiKit::Paths.new(%w[user.groups])) }- it "lets a request read a path through a relationship" do+ it "allows a path through a relationship" doexpect(allowed_paths.map(&:to_s)).to eq(%w[user.groups])end- context "when the path reads a relationship no resource declares" do+ context "when the path holds a relationship no resource declares" dobefore { topic_resource.includes("user.badges") }- it "refuses to read the resource" do+ it "raises an unresolved path" doexpect { allowed_paths }.to raise_error(JsonApiKit::Declarations::IncludePaths::Unresolved,/user\.badges/,@@ -450,7 +454,7 @@ RSpec.describe JsonApiKit::Resource dobefore { child.includes("posts.groups") }- it "reads the paths declared above it" do+ it "allows the paths declared above it" doexpect(child.allow(JsonApiKit::Paths.new(%w[user.groups])).map(&:to_s)).to eq(%w[user.groups],)@@ -490,7 +494,7 @@ RSpec.describe JsonApiKit::Resource doendcontext "when the default is larger than the maximum" do- it "refuses the declaration" do+ it "raises an out-of-range limit" doexpect {Class.new(described_class) domodel Topic@@ -503,7 +507,7 @@ RSpec.describe JsonApiKit::Resource doenddescribe ".page_size" do- it "returns the size a page reads at" do+ it "returns the size of a page" doexpect(topic_resource.page_size).to eq(2)endend@@ -515,7 +519,7 @@ RSpec.describe JsonApiKit::Resource doit { is_expected.to be_anchored_by(anchor_name: :created_at, ordering:) }- context "when the order does not read by that anchor" do+ context "when the order does not hold that anchor" dolet(:ordering) { { "ran_at" => :desc } }it { is_expected.not_to be_anchored_by(anchor_name: :created_at, ordering:) }@@ -552,7 +556,7 @@ RSpec.describe JsonApiKit::Resource dodescribe ".all" dobefore { allow(JsonApiKit::Query::Collection).to receive(:new) }- it "reads a listing for the request a caller sends" do+ it "builds a listing for the request a caller sends" dotopic_resource.all({ sort: { created_at: :asc } }, guardian:)expect(JsonApiKit::Query::Collection).to have_received(:new).with(@@ -580,7 +584,7 @@ RSpec.describe JsonApiKit::Resource doendcontext "when no column of the order allows null" do- it "reads the listing in one segment" do+ it "orders the listing in one segment" doexpect(topic_resource.order("created_at" => :desc).segments.size).to eq(1)endenddiff --git a/spec/lib/json_api_kit/sideload_spec.rb b/spec/lib/json_api_kit/sideload_spec.rbindex 03854be90c2..0084eec6d6c 100644--- a/spec/lib/json_api_kit/sideload_spec.rb+++ b/spec/lib/json_api_kit/sideload_spec.rb@@ -53,7 +53,7 @@ RSpec.describe JsonApiKit::Sideload doendend- context "when a path reads past the relationship" do+ context "when a path goes past the relationship" dolet(:paths) { JsonApiKit::Paths.new(%w[user.groups]).next_for("user") }before { allow(relationship).to receive(:listing).and_call_original }@@ -71,7 +71,9 @@ RSpec.describe JsonApiKit::Sideload dolet(:params) { { fields: { users: %w[username] } } }it "renders the related record as those fields" do- expect(linkage.records.map(&:attributes)).to eq([{ "username" => author.username }])+ expect(linkage.records.map(&:attributes)).to eq(+ [{ JsonApiKit::Name::Field.new(value: "username", type: "users") => author.username }],+ )endend@@ -79,14 +81,14 @@ RSpec.describe JsonApiKit::Sideload dofab!(:another) { Fabricate(:topic, user: author, title: "Another topic by that author") }let(:records) { [topic, another] }- let(:reads_of_users) do+ let(:user_queries) dotrack_sql_queries { rows.each { sideload.linkage_for(it) } }.grep(/FROM "users"/).sizeenddef related_record(row) = sideload.linkage_for(row).records.first- it "reads the related rows of them all in one query" do- expect(reads_of_users).to eq(1)+ it "loads the related rows of them all in one query" do+ expect(user_queries).to eq(1)endit "gives two rows that relate to one row the same record" dodiff --git a/spec/lib/json_api_kit/version_change/pass_through_spec.rb b/spec/lib/json_api_kit/version_change/pass_through_spec.rbnew file mode 100644index 00000000000..3514e5d31a9--- /dev/null+++ b/spec/lib/json_api_kit/version_change/pass_through_spec.rb@@ -0,0 +1,31 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::PassThrough do+ subject(:pass_through) { described_class.new(name) }++ let(:name) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }++ describe "#current" do+ it "returns the name" do+ expect(pass_through.current).to eq(name)+ end+ end++ describe "#current_pairs" do+ it "returns the name with the value" do+ expect(pass_through.current_pairs("A")).to eq([[name, "A"]])+ end+ end++ describe "#previous" do+ it "returns the name" do+ expect(pass_through.previous).to eq(name)+ end+ end++ describe "#previous_pairs" do+ it "returns the name with the value" do+ expect(pass_through.previous_pairs("A")).to eq([[name, "A"]])+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/rename_spec.rb b/spec/lib/json_api_kit/version_change/rename_spec.rbindex 101d03dce6b..4cb9aff6289 100644--- a/spec/lib/json_api_kit/version_change/rename_spec.rb+++ b/spec/lib/json_api_kit/version_change/rename_spec.rb@@ -1,59 +1,76 @@# frozen_string_literal: trueRSpec.describe JsonApiKit::VersionChange::Rename do- subject(:rename) do- described_class.new(kind: :field, type: "topics", from: "posted_at", to: "created_at")- end+ subject(:rename) { described_class.new(from: old_name, to: new_name, up:, down:) }+ let(:up) { JsonApiKit::VersionChange::Declarations::NO_CONVERSION }+ let(:down) { JsonApiKit::VersionChange::Declarations::NO_CONVERSION }let(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "topics") }let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "topics") }describe "#current" do- it "returns the new name for the old one" do- expect(rename.current(old_name)).to eq(new_name)+ it "returns the new name" do+ expect(rename.current).to eq(new_name)end+ end- context "when the name is of another kind" do- let(:old_name) { JsonApiKit::Name::Sort.new(value: "posted_at", type: "topics") }+ describe "#current_pairs" do+ subject(:current_pairs) { rename.current_pairs(value) }- it "returns the name" do- expect(rename.current(old_name)).to eq(old_name)- end+ let(:value) { "2026/08/01" }++ it "returns one pair, the new name with the value" do+ expect(current_pairs).to eq([[new_name, "2026/08/01"]])end- context "when the name is of another type" do- let(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "users") }+ context "when the rename converts the value" do+ let(:down) { ->(date) { date.to_s.tr("-", "/") } }+ let(:up) { ->(date) { date.to_s.tr("/", "-") } }- it "returns the name" do- expect(rename.current(old_name)).to eq(old_name)+ it "returns the new name with the converted value" do+ expect(current_pairs).to eq([[new_name, "2026-08-01"]])+ end++ context "when the value is null" do+ let(:value) { nil }++ it "gives the converter the null value" do+ expect(current_pairs).to eq([[new_name, ""]])+ endendendenddescribe "#previous" do- it "returns the old name for the new one" do- expect(rename.previous(new_name)).to eq(old_name)+ it "returns the old name" do+ expect(rename.previous).to eq(old_name)end+ end- context "when the name is of another kind" do- let(:new_name) { JsonApiKit::Name::Sort.new(value: "created_at", type: "topics") }+ describe "#previous_pairs" do+ subject(:previous_pairs) { rename.previous_pairs(value) }- it "returns the name" do- expect(rename.previous(new_name)).to eq(new_name)- end+ let(:value) { "2026-08-01" }++ it "returns one pair, the old name with the value" do+ expect(previous_pairs).to eq([[old_name, "2026-08-01"]])end- context "when the name is of another type" do- let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "users") }+ context "when the rename converts the value" do+ let(:down) { ->(date) { date.to_s.tr("-", "/") } }+ let(:up) { ->(date) { date.tr("/", "-") } }- it "returns the name" do- expect(rename.previous(new_name)).to eq(new_name)+ it "returns the old name with the converted value" do+ expect(previous_pairs).to eq([[old_name, "2026/08/01"]])end- end- end- describe "#introduces?" do- it { expect(rename).to be_introduces(new_name) }- it { expect(rename).not_to be_introduces(old_name) }+ context "when the value is null" do+ let(:value) { nil }++ it "gives the converter the null value" do+ expect(previous_pairs).to eq([[old_name, ""]])+ end+ end+ endendenddiff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rbindex efbd87b2661..2b2fe40d968 100644--- a/spec/lib/json_api_kit/version_change_spec.rb+++ b/spec/lib/json_api_kit/version_change_spec.rb@@ -10,6 +10,18 @@ module JsonApiKitSpecendend+ class ReshapeThingsWordsToTitle < JsonApiKit::VersionChange+ version "2026-09-20"+ description "The `words` attribute of the things resource becomes `title`, one string."++ resource :things do+ renamed_attribute from: :words,+ to: :title,+ down: ->(title) { title.to_s.split(" ") },+ up: ->(words) { words.to_a.join(" ") }+ end+ end+class RenameThingsAndPeople < JsonApiKit::VersionChangeversion "2026-10-01"description "Two resources change their names."@@ -25,8 +37,9 @@ module JsonApiKitSpecendRSpec.describe JsonApiKit::VersionChange do- subject(:change) { JsonApiKitSpec::RenameThingsLabelToName.new(__FILE__) }+ subject(:change) { change_class.new(__FILE__) }+ let(:change_class) { JsonApiKitSpec::RenameThingsLabelToName }let(:version) { JsonApiKit::ApiVersion.parse("2026-09-15") }let(:later_version) { JsonApiKit::ApiVersion.parse("2026-10-01") }let(:fixtures) { Rails.root.join("spec/fixtures/json_api_kit") }@@ -88,6 +101,18 @@ RSpec.describe JsonApiKit::VersionChange doit { expect { changes }.to raise_error(ArgumentError, /has no description/) }end++ context "when a change renames one name twice" do+ let(:directory) { "api_changes_with_two_renames_from_one_name" }++ it { expect { changes }.to raise_error(ArgumentError, /renames label twice/) }+ end++ context "when a change renames two names to one name" do+ let(:directory) { "api_changes_with_two_renames_to_one_name" }++ it { expect { changes }.to raise_error(ArgumentError, /renames two names to title/) }+ endenddescribe ".after" do@@ -111,6 +136,32 @@ RSpec.describe JsonApiKit::VersionChange doendend+ describe ".resource" do+ context "when a rename declares one converter only" do+ subject(:declaration) do+ Class.new(described_class) do+ version "2026-09-15"+ description "Half a shape change."+ resource(:things) { renamed_attribute from: :a, to: :b, down: ->(value) { value } }+ end+ end++ it { expect { declaration }.to raise_error(ArgumentError, /both up: and down:/) }+ end++ context "when a converter is not callable" do+ subject(:declaration) do+ Class.new(described_class) do+ version "2026-09-15"+ description "A converter that is not one."+ resource(:things) { renamed_attribute from: :a, to: :b, up: nil, down: nil }+ end+ end++ it { expect { declaration }.to raise_error(ArgumentError, /must respond to call/) }+ end+ end+describe "#version" doit "returns the version of the change" doexpect(change.version).to eq(version)@@ -148,7 +199,7 @@ RSpec.describe JsonApiKit::VersionChange doendend- context "when the name is a filter with that name" do+ context "when the name is a filter with the same spelling" dolet(:name) { JsonApiKit::Name::Filter.new(value: "label", type: "things") }it "returns the name" do@@ -169,6 +220,39 @@ RSpec.describe JsonApiKit::VersionChange doendend+ describe "#current_attributes" do+ subject(:current_attributes) { change.current_attributes(attributes) }++ let(:attributes) { { name => "A", other_name => "B" } }+ let(:other_name) { JsonApiKit::Name::Field.new(value: "size", type: "things") }++ it "returns a renamed attribute under its current name" do+ expect(current_attributes).to include(name.with(value: "name") => "A")+ end++ it "keeps an attribute the change does not rename" do+ expect(current_attributes).to include(other_name => "B")+ end++ context "when the change reshapes the value" do+ let(:change_class) { JsonApiKitSpec::ReshapeThingsWordsToTitle }+ let(:attributes) { { name => %w[Bands of a listing] } }+ let(:name) { JsonApiKit::Name::Field.new(value: "words", type: "things") }++ it "returns the value in its current shape" do+ expect(current_attributes).to eq(name.with(value: "title") => "Bands of a listing")+ end++ context "when the value is null" do+ let(:attributes) { { name => nil } }++ it "returns the value the converter gives for null" do+ expect(current_attributes).to eq(name.with(value: "title") => "")+ end+ end+ end+ end+describe "#previous" dosubject(:previous_name) { change.previous(name) }@@ -179,15 +263,37 @@ RSpec.describe JsonApiKit::VersionChange doendend- describe "#introduces?" do- context "when the change renames another name to this one" do- let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }+ describe "#previous_attributes" do+ subject(:previous_attributes) { change.previous_attributes(attributes) }++ let(:attributes) { { name => "A", other_name => "B" } }+ let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }+ let(:other_name) { JsonApiKit::Name::Field.new(value: "size", type: "things") }++ it "returns a renamed attribute under its name before the change" do+ expect(previous_attributes).to include(name.with(value: "label") => "A")+ end- it { expect(change).to be_introduces(name) }+ it "keeps an attribute the change does not rename" do+ expect(previous_attributes).to include(other_name => "B")end- context "when the change renames this name away" do- it { expect(change).not_to be_introduces(name) }+ context "when the change reshapes the value" do+ let(:change_class) { JsonApiKitSpec::ReshapeThingsWordsToTitle }+ let(:attributes) { { name => "Bands of a listing" } }+ let(:name) { JsonApiKit::Name::Field.new(value: "title", type: "things") }++ it "returns the value in its shape before the change" do+ expect(previous_attributes).to eq(name.with(value: "words") => %w[Bands of a listing])+ end++ context "when the value is null" do+ let(:attributes) { { name => nil } }++ it "returns the value the converter gives for null" do+ expect(previous_attributes).to eq(name.with(value: "words") => [])+ end+ endendendend