Skip to content

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

DEV: Add version changes to the JSON:API kit (#43196)

Loïc Guitaut44cb8b773cc8
diff --git a/app/controllers/json_api_kit/base_controller/versioning.rb b/app/controllers/json_api_kit/base_controller/versioning.rb
index 4c4c515327a..664ccd8996f 100644
--- a/app/controllers/json_api_kit/base_controller/versioning.rb
+++ b/app/controllers/json_api_kit/base_controller/versioning.rb
@@ -10,14 +10,16 @@ module JsonApiKit
private
def resolve_version
- response.headers[ApiVersion::HEADER] = Timeline.resolve(requested_version).to_s
+ response.headers[ApiVersion::HEADER] = version.to_s
rescue Error => error
render_document(Document::Errors.new(error))
end
+ def version = @version ||= Timeline.resolve(requested_version)
+
def requested_version = request.headers[ApiVersion::HEADER]
- def glossary = @glossary ||= Glossary.resource
+ def glossary = @glossary ||= Glossary.resource(version)
end
end
end
diff --git a/config/api_changes/.keep b/config/api_changes/.keep
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/config/initializers/json_api_kit.rb b/config/initializers/json_api_kit.rb
new file mode 100644
index 00000000000..f9f14e04f4c
--- /dev/null
+++ b/config/initializers/json_api_kit.rb
@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Rails.application.config.after_initialize { JsonApiKit::VersionChange.all }
diff --git a/lib/json_api_kit/api_version.rb b/lib/json_api_kit/api_version.rb
index b80d2e190c2..99efa090a4c 100644
--- a/lib/json_api_kit/api_version.rb
+++ b/lib/json_api_kit/api_version.rb
@@ -64,6 +64,10 @@ module JsonApiKit
date <=> other.date
end
+ def eql?(other) = (self <=> other) == 0
+
+ def hash = date.hash
+
def future? = date.future?
def to_s = date.iso8601
diff --git a/lib/json_api_kit/document.rb b/lib/json_api_kit/document.rb
index fcd42bc10c6..bc0e29694bd 100644
--- a/lib/json_api_kit/document.rb
+++ b/lib/json_api_kit/document.rb
@@ -3,7 +3,8 @@
module JsonApiKit
class Document
def self.build(parameters, resource:, urls:, glossary:)
- declared_parameters = Request::Parameters.new(parameters.to_hash, glossary:).to_h
+ declared_parameters =
+ Request::Parameters.new(parameters.to_hash.deep_stringify_keys, glossary:, resource:).to_h
contract_class
.new(
**declared_parameters.deep_dup,
diff --git a/lib/json_api_kit/document/resource_object.rb b/lib/json_api_kit/document/resource_object.rb
index dad3f279e9c..3456fa8dbf9 100644
--- a/lib/json_api_kit/document/resource_object.rb
+++ b/lib/json_api_kit/document/resource_object.rb
@@ -18,11 +18,17 @@ module JsonApiKit
attr_reader :record, :urls, :glossary, :meta
- def attributes = record.attributes.transform_keys { glossary.member_name(it) }
+ 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 relationships
record.relationships.to_h do |name, linkage|
- member = glossary.member_name(name)
+ member = member_value(relationship(name))
[member, RelationshipObject.new(linkage, urls:, 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 7bf2bf809ef..ea55a93528e 100644
--- a/lib/json_api_kit/glossary.rb
+++ b/lib/json_api_kit/glossary.rb
@@ -2,18 +2,47 @@
module JsonApiKit
class Glossary
+ class Correction < StandardError
+ attr_reader :name
+
+ def initialize(name)
+ @name = name
+ super("Use #{name}.")
+ end
+ end
+
+ class NotAMemberName < BadRequest
+ attr_reader :raw, :member
+
+ def initialize(raw, member, parameter: nil)
+ @raw = raw
+ @member = member
+ @parameter = parameter
+ super("Use #{member}, not #{raw}.")
+ end
+
+ def title = "Invalid member name"
+
+ def source = { parameter: @parameter }.compact
+
+ def at(parameter) = self.class.new(raw, member, parameter:)
+ end
+
class << self
def kit = new([CasingRule])
- # TODO: add the versioning rule here (next PR)
- def resource = kit
+ def resource(version) = new([CasingRule, VersionRule.new(version)])
end
def initialize(rules)
@rules = rules
end
- def declared_name(raw) = rules.reduce(raw) { |name, rule| rule.declared_name(name) }
+ def declared_name(name)
+ rules.reduce(name) { |result, rule| rule.declared_name(result) }
+ rescue Correction => correction
+ raise NotAMemberName.new(name, member_name(correction.name))
+ end
def member_name(name)
rules.reverse_each.reduce(name) { |member, rule| rule.member_name(member) }
diff --git a/lib/json_api_kit/glossary/casing_rule.rb b/lib/json_api_kit/glossary/casing_rule.rb
index ea250f81939..6c4d6a0870f 100644
--- a/lib/json_api_kit/glossary/casing_rule.rb
+++ b/lib/json_api_kit/glossary/casing_rule.rb
@@ -6,33 +6,19 @@ module JsonApiKit
CAMEL_BOUNDARY = /(?<before>[a-z\d])(?<capital>[A-Z])/
SNAKE_BOUNDARY = /_(?<letter>[a-z\d])/
- class NotAMemberName < BadRequest
- attr_reader :raw, :member
-
- def initialize(raw, member, parameter: nil)
- @raw = raw
- @member = member
- @parameter = parameter
- super("Use #{member}, not #{raw}.")
- end
-
- def title = "Invalid member name"
-
- def source = { parameter: @parameter }.compact
-
- def at(parameter) = self.class.new(raw, member, parameter:)
- end
-
class << self
- def declared_name(raw)
- name = raw.to_s.gsub(CAMEL_BOUNDARY, '\k<before>_\k<capital>').downcase
- member = member_name(name)
- raise NotAMemberName.new(raw, member) unless member == raw.to_s
- name
+ def declared_name(name)
+ snake_case(name).tap { raise Correction.new(it) unless member_name(it) == name }
end
def member_name(name)
- name.to_s.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase }
+ name.convert { it.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase } }
+ end
+
+ private
+
+ def snake_case(name)
+ name.convert { it.gsub(CAMEL_BOUNDARY, '\k<before>_\k<capital>').downcase }
end
end
end
diff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rb
new file mode 100644
index 00000000000..b11a4dcc8da
--- /dev/null
+++ b/lib/json_api_kit/glossary/version_rule.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Glossary
+ class VersionRule
+ def initialize(version)
+ @changes = VersionChange.after(version)
+ end
+
+ def declared_name(name)
+ current_name(name).tap { raise Correction.new(it) unless member_name(it) == name }
+ end
+
+ def member_name(name)
+ changes.reverse_each.reduce(name) { |result, change| change.previous(result) }
+ end
+
+ private
+
+ attr_reader :changes
+
+ def current_name(name) = changes.reduce(name) { |result, change| change.current(result) }
+ end
+ end
+end
diff --git a/lib/json_api_kit/name.rb b/lib/json_api_kit/name.rb
new file mode 100644
index 00000000000..3b2d4022fb1
--- /dev/null
+++ b/lib/json_api_kit/name.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ def convert = with(value: yield(value))
+
+ def to_s = value
+ end
+end
diff --git a/lib/json_api_kit/name/anchor.rb b/lib/json_api_kit/name/anchor.rb
new file mode 100644
index 00000000000..7ce5bbea41b
--- /dev/null
+++ b/lib/json_api_kit/name/anchor.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Anchor =
+ Data.define(:value, :type) do
+ include Name
+
+ def kind = :anchor
+ end
+ end
+end
diff --git a/lib/json_api_kit/name/field.rb b/lib/json_api_kit/name/field.rb
new file mode 100644
index 00000000000..b44a3e0bd62
--- /dev/null
+++ b/lib/json_api_kit/name/field.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Field =
+ Data.define(:value, :type) do
+ include Name
+
+ def kind = :field
+ end
+ end
+end
diff --git a/lib/json_api_kit/name/filter.rb b/lib/json_api_kit/name/filter.rb
new file mode 100644
index 00000000000..7af6576c613
--- /dev/null
+++ b/lib/json_api_kit/name/filter.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Filter =
+ Data.define(:value, :type) do
+ include Name
+
+ def kind = :filter
+ end
+ end
+end
diff --git a/lib/json_api_kit/name/member.rb b/lib/json_api_kit/name/member.rb
new file mode 100644
index 00000000000..50b399d49ba
--- /dev/null
+++ b/lib/json_api_kit/name/member.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Member =
+ Data.define(:value) do
+ include Name
+
+ def kind = :member
+ end
+ end
+end
diff --git a/lib/json_api_kit/name/relationship.rb b/lib/json_api_kit/name/relationship.rb
new file mode 100644
index 00000000000..9703d8b9269
--- /dev/null
+++ b/lib/json_api_kit/name/relationship.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Relationship =
+ Data.define(:value, :type) do
+ include Name
+
+ def kind = :relationship
+ end
+ end
+end
diff --git a/lib/json_api_kit/name/sort.rb b/lib/json_api_kit/name/sort.rb
new file mode 100644
index 00000000000..9a6ea28f791
--- /dev/null
+++ b/lib/json_api_kit/name/sort.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ Sort =
+ Data.define(:value, :type) do
+ include Name
+
+ def kind = :sort
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/contract/error.rb b/lib/json_api_kit/request/contract/error.rb
index 3c07da50bf8..e9976fc74b1 100644
--- a/lib/json_api_kit/request/contract/error.rb
+++ b/lib/json_api_kit/request/contract/error.rb
@@ -26,12 +26,12 @@ module JsonApiKit
def meta = @meta&.call(self) || {}
def parameter
- ParameterName.new(*error.attribute.to_s.split(".").map { member_name(it) })
+ ParameterName.new(*error.attribute.to_s.split(".").map { member_value(member(it)) })
end
- def name = member_name(options[:name])
+ def name = member_value(options[:name])
- def key = member_name(options[:key])
+ def key = member_value(options[:key])
def member_parameter(member = name) = parameter.member(member)
@@ -45,9 +45,11 @@ module JsonApiKit
attr_reader :error, :glossary
- def member_name(name) = glossary.member_name(name)
+ def member_value(name) = glossary.member_name(name).value
- def page_parameter(name) = parameter.family.member(member_name(name))
+ def member(value) = Name::Member.new(value: value.to_s)
+
+ def page_parameter(name) = parameter.family.member(member_value(member(name)))
end
end
end
diff --git a/lib/json_api_kit/request/contract/fields.rb b/lib/json_api_kit/request/contract/fields.rb
index f2306f21d5f..d473c01cce5 100644
--- a/lib/json_api_kit/request/contract/fields.rb
+++ b/lib/json_api_kit/request/contract/fields.rb
@@ -36,7 +36,7 @@ module JsonApiKit
def check_fields
fields.each_key do |type|
next if fields[type].is_a?(Array)
- errors.add(:fields, :bad_value, name: type, message: "bad value")
+ errors.add(:fields, :bad_value, type:, message: "bad value")
end
end
end
diff --git a/lib/json_api_kit/request/contract/filtering.rb b/lib/json_api_kit/request/contract/filtering.rb
index 8bf1c63586f..4c61916fcf2 100644
--- a/lib/json_api_kit/request/contract/filtering.rb
+++ b/lib/json_api_kit/request/contract/filtering.rb
@@ -15,12 +15,24 @@ module JsonApiKit
private
- def check_filter_names = refuse_unknown(:filter, filter.keys - resource.filter_names)
+ def check_filter_names
+ refuse_unknown(
+ :filter,
+ (filter.keys - resource.filter_names).map do
+ Name::Filter.new(value: it.to_s, type: resource.type)
+ end,
+ )
+ end
def check_filter_values
filter.each_key do |name|
next if comparable?(filter[name]) || listed?(filter[name])
- errors.add(:filter, :bad_value, name:, message: "bad value")
+ errors.add(
+ :filter,
+ :bad_value,
+ name: Name::Filter.new(value: name.to_s, type: resource.type),
+ message: "bad value",
+ )
end
end
diff --git a/lib/json_api_kit/request/contract/including.rb b/lib/json_api_kit/request/contract/including.rb
index ff19d7fc2f2..d3203a3680b 100644
--- a/lib/json_api_kit/request/contract/including.rb
+++ b/lib/json_api_kit/request/contract/including.rb
@@ -26,7 +26,13 @@ module JsonApiKit
private
def check_include_paths
- refuse_unknown(:include, Paths.new(include).reject { resource.paths_include?(it) })
+ refuse_unknown(
+ :include,
+ Paths
+ .new(include)
+ .reject { resource.paths_include?(it) }
+ .map { Name::Member.new(value: it.to_s) },
+ )
end
end
end
diff --git a/lib/json_api_kit/request/contract/mapper.rb b/lib/json_api_kit/request/contract/mapper.rb
index cf6c4a533c8..02765e4910f 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[:name])} must be a list of field names."
+ "#{error.member_parameter(error.options[:type])} must be a list of field names."
end,
- source: ->(error) { error.member_parameter(error.options[:name]) },
+ source: ->(error) { error.member_parameter(error.options[:type]) },
},
%i[sort bad_shape] => {
title: "Invalid sort parameter",
diff --git a/lib/json_api_kit/request/contract/paging.rb b/lib/json_api_kit/request/contract/paging.rb
index a3997aab18e..edebe2cc9bf 100644
--- a/lib/json_api_kit/request/contract/paging.rb
+++ b/lib/json_api_kit/request/contract/paging.rb
@@ -115,13 +115,23 @@ module JsonApiKit
def check_anchor_name
([anchor_name.to_s] - resource.anchor_names).each do
- errors.add(:anchor, :no_such_name, name: it, message: "no such name")
+ errors.add(
+ :anchor,
+ :no_such_name,
+ name: Name::Anchor.new(value: it.to_s, type: resource.type),
+ message: "no such name",
+ )
end
end
def check_anchor_value
return unless anchor_value.is_a?(Enumerable)
- errors.add(:anchor, :bad_value, name: anchor_name, message: "bad value")
+ errors.add(
+ :anchor,
+ :bad_value,
+ name: Name::Anchor.new(value: anchor_name.to_s, type: resource.type),
+ message: "bad value",
+ )
end
def check_anchor_ordering
@@ -129,8 +139,12 @@ module JsonApiKit
errors.add(
:anchor,
:not_the_sort,
- name: anchor_name,
- key: resource.order(ordering).leading.name,
+ name: Name::Anchor.new(value: anchor_name.to_s, type: resource.type),
+ key:
+ Name::Sort.new(
+ value: resource.order(ordering).leading.name.to_s,
+ type: resource.type,
+ ),
message: "not the sort",
)
end
diff --git a/lib/json_api_kit/request/contract/sorting.rb b/lib/json_api_kit/request/contract/sorting.rb
index 57c0673aa62..24c98de4b65 100644
--- a/lib/json_api_kit/request/contract/sorting.rb
+++ b/lib/json_api_kit/request/contract/sorting.rb
@@ -37,7 +37,14 @@ module JsonApiKit
private
- def check_sort_names = refuse_unknown(:sort, sort.keys - resource.sort_names)
+ def check_sort_names
+ refuse_unknown(
+ :sort,
+ (sort.keys - resource.sort_names).map do
+ Name::Sort.new(value: it.to_s, type: resource.type)
+ end,
+ )
+ end
def check_sort_directions
sort.each_value do |direction|
diff --git a/lib/json_api_kit/request/family.rb b/lib/json_api_kit/request/family.rb
new file mode 100644
index 00000000000..83905dbf525
--- /dev/null
+++ b/lib/json_api_kit/request/family.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ LIST = ","
+ LIST_ITEM = /\A(?<direction>-?)(?<name>.*)\z/m
+
+ def initialize(glossary:, type:)
+ @glossary = glossary
+ @type = type
+ end
+
+ private
+
+ attr_reader :glossary, :type
+
+ def names(value, path, &name_for)
+ case value
+ when Hash
+ value.transform_keys { declared_name(name_for.call(it), path + [it]) }
+ when Array
+ value.map { names(it, path, &name_for) }
+ when String, Symbol
+ value.to_s.split(LIST, -1).map { list_item(it, path, &name_for) }.join(LIST)
+ else
+ value
+ end
+ end
+
+ def list_item(value, path)
+ direction, name = LIST_ITEM.match(value).captures
+ "#{direction}#{declared_name(yield(name), path)}"
+ end
+
+ def declared_name(name, path)
+ glossary.declared_name(name).value
+ rescue Glossary::NotAMemberName => error
+ raise error.at(ParameterName.new(*path).to_s)
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/fields.rb b/lib/json_api_kit/request/family/fields.rb
new file mode 100644
index 00000000000..8d893094eaf
--- /dev/null
+++ b/lib/json_api_kit/request/family/fields.rb
@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ class Fields < Family
+ def declared_value(value, path)
+ return value unless value.is_a?(Hash)
+ value.to_h do |fieldset_type, fields|
+ [
+ fieldset_type,
+ names(fields, path + [fieldset_type]) do
+ Name::Field.new(value: it, type: fieldset_type)
+ end,
+ ]
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/filter.rb b/lib/json_api_kit/request/family/filter.rb
new file mode 100644
index 00000000000..2fa716dedac
--- /dev/null
+++ b/lib/json_api_kit/request/family/filter.rb
@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ class Filter < Family
+ def declared_value(value, path)
+ return value unless value.is_a?(Hash)
+ value.transform_keys { declared_name(Name::Filter.new(value: it, type:), path + [it]) }
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/include.rb b/lib/json_api_kit/request/family/include.rb
new file mode 100644
index 00000000000..3289b29ac2f
--- /dev/null
+++ b/lib/json_api_kit/request/family/include.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ class Include < Family
+ def declared_value(value, path) = names(value, path) { Name::Member.new(value: it) }
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/other.rb b/lib/json_api_kit/request/family/other.rb
new file mode 100644
index 00000000000..f0217aa64b6
--- /dev/null
+++ b/lib/json_api_kit/request/family/other.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ class Other < Family
+ def declared_value(value, _path) = value
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/page.rb b/lib/json_api_kit/request/family/page.rb
new file mode 100644
index 00000000000..530b2da38f1
--- /dev/null
+++ b/lib/json_api_kit/request/family/page.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ class Page < Family
+ ANCHOR = "anchor"
+
+ def declared_value(value, path)
+ return value unless value.is_a?(Hash)
+ value.to_h do |member, member_value|
+ key = declared_name(Name::Member.new(value: member), path + [member])
+ [key, key == ANCHOR ? anchor(member_value, path + [key]) : member_value]
+ end
+ end
+
+ private
+
+ def anchor(value, path) = names(value, path) { Name::Anchor.new(value: it, type:) }
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/sort.rb b/lib/json_api_kit/request/family/sort.rb
new file mode 100644
index 00000000000..841e9fe6849
--- /dev/null
+++ b/lib/json_api_kit/request/family/sort.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Family
+ class Sort < Family
+ def declared_value(value, path) = names(value, path) { Name::Sort.new(value: it, type:) }
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/parameters.rb b/lib/json_api_kit/request/parameters.rb
index 85653547a15..8f5f272a397 100644
--- a/lib/json_api_kit/request/parameters.rb
+++ b/lib/json_api_kit/request/parameters.rb
@@ -3,56 +3,37 @@
module JsonApiKit
class Request
class Parameters
- FIELDSETS_AT = %w[fields].freeze
- NAMES_AT = [%w[sort], %w[include], %w[page anchor]].freeze
-
- def initialize(raw, glossary:)
+ FAMILIES = {
+ "fields" => Family::Fields,
+ "sort" => Family::Sort,
+ "filter" => Family::Filter,
+ "page" => Family::Page,
+ "include" => Family::Include,
+ }.freeze
+
+ def initialize(raw, glossary:, resource:)
@raw = raw
@glossary = glossary
+ @resource = resource
end
- def to_h = declared_names(raw, [])
-
- private
-
- attr_reader :raw, :glossary
-
- def declared_names(parameters, path)
- parameters.to_h do |name, value|
- key = declared_at(name, path + [name.to_s])
- [key, declared_value(value, path + [key])]
+ def to_h
+ raw.to_h do |family, value|
+ key = declared_name(family)
+ [key, family_for(key).declared_value(value, [key])]
end
end
- def declared_value(value, path)
- return fieldsets(value, path) if path == FIELDSETS_AT
- return names(value, path) if path.in?(NAMES_AT)
- return declared_names(value, path) if value.is_a?(Hash)
- value
- end
+ private
- def fieldsets(value, path)
- return value unless value.is_a?(Hash)
- value.to_h { |type, fields| [type, names(fields, path + [type.to_s])] }
- end
+ attr_reader :raw, :glossary, :resource
- def names(value, path)
- case value
- when Hash
- value.transform_keys { declared_at(it, path + [it.to_s]) }
- when Array
- value.map { names(it, path) }
- when String, Symbol
- declared_at(value, path)
- else
- value
- end
- end
+ def family_for(key) = FAMILIES.fetch(key, Family::Other).new(glossary:, type: resource.type)
- def declared_at(raw, path)
- glossary.declared_name(raw)
- rescue Glossary::CasingRule::NotAMemberName => error
- raise error.at(ParameterName.new(*path).to_s)
+ def declared_name(family)
+ glossary.declared_name(Name::Member.new(value: family)).value
+ rescue Glossary::NotAMemberName => error
+ raise error.at(ParameterName.new(family).to_s)
end
end
end
diff --git a/lib/json_api_kit/timeline.rb b/lib/json_api_kit/timeline.rb
index 930dba58dd6..8e96ceb8043 100644
--- a/lib/json_api_kit/timeline.rb
+++ b/lib/json_api_kit/timeline.rb
@@ -10,7 +10,7 @@ module JsonApiKit
private
- def core = @core ||= new([FIRST_RELEASE])
+ def core = new([FIRST_RELEASE, *VersionChange.all.map(&:version)].uniq)
end
def initialize(versions)
diff --git a/lib/json_api_kit/url.rb b/lib/json_api_kit/url.rb
index 0383677581a..e04f0e25c34 100644
--- a/lib/json_api_kit/url.rb
+++ b/lib/json_api_kit/url.rb
@@ -7,8 +7,7 @@ module JsonApiKit
KIT = Glossary.kit
REPLACED_MEMBERS =
%w[after before anchor before_size after_size include_anchor]
- .map { KIT.member_name(it) }
- .freeze
+ .map { KIT.member_name(Name::Member.new(value: it)).value }
.freeze
def initialize(address, parameters = {})
@@ -33,7 +32,9 @@ module JsonApiKit
def page_parameters = parameters.fetch(PAGE, {})
- def member_names(page) = page.transform_keys { KIT.member_name(it) }
+ def member_names(page)
+ page.transform_keys { KIT.member_name(Name::Member.new(value: it.to_s)).value }
+ end
def query_string = Rack::Utils.build_nested_query(parameters).presence.try { "?#{it}" }
end
diff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rb
new file mode 100644
index 00000000000..06db6587afd
--- /dev/null
+++ b/lib/json_api_kit/version_change.rb
@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ CHANGES_DIRECTORY = Rails.root.join("config/api_changes")
+ DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}_/
+
+ class << self
+ def all = @all ||= read(CHANGES_DIRECTORY)
+
+ def after(version) = all.select { it.version > version }
+
+ def read(directory)
+ Dir
+ .glob(directory.join("*.rb"))
+ .map { change_in(it) }
+ .each(&:verify!)
+ .sort_by { [it.version, it.source] }
+ end
+
+ def version(raw = nil)
+ @version = ApiVersion.parse(raw) if raw
+ @version
+ rescue ApiVersion::NotADate
+ raise ArgumentError, "The version of #{self}, #{raw}, is not a date."
+ end
+
+ def description(text = nil)
+ @description = text if text
+ @description
+ end
+
+ def resource(type, &declarations)
+ transformations.concat(Declarations.new(type).tap { it.instance_eval(&declarations) }.to_a)
+ end
+
+ def transformations = @transformations ||= []
+
+ private
+
+ def change_in(source)
+ constant = File.basename(source, ".rb").sub(DATE_PREFIX, "").camelize
+ Object.send(:remove_const, constant) if Object.const_defined?(constant, false)
+ load source
+ constant.constantize.new(source)
+ end
+ end
+
+ delegate :version, :description, :transformations, to: :class
+
+ attr_reader :source
+
+ def initialize(source)
+ @source = source
+ end
+
+ def verify!
+ raise ArgumentError, "#{source} has no version." if version.nil?
+ raise ArgumentError, "#{source} is dated in the future." if version.future?
+ if version <= Timeline::FIRST_RELEASE
+ raise ArgumentError, "#{source} is dated on or before the first release."
+ end
+ raise ArgumentError, "#{source} has no description." if description.blank?
+ 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) }
+ end
+
+ def previous(name)
+ transformations
+ .reverse_each
+ .reduce(name) { |result, transformation| transformation.previous(result) }
+ end
+
+ def introduces?(name) = transformations.any? { it.introduces?(name) }
+ end
+end
diff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rb
new file mode 100644
index 00000000000..50aa15ea8bc
--- /dev/null
+++ b/lib/json_api_kit/version_change/declarations.rb
@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ class Declarations
+ DERIVED_FROM_AN_ATTRIBUTE = %i[field sort anchor].freeze
+
+ 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)
+ end
+ end
+
+ def to_a = transformations
+
+ private
+
+ attr_reader :type, :transformations
+ end
+ end
+end
diff --git a/lib/json_api_kit/version_change/rename.rb b/lib/json_api_kit/version_change/rename.rb
new file mode 100644
index 00000000000..bb0749e2cf8
--- /dev/null
+++ b/lib/json_api_kit/version_change/rename.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ Rename =
+ Data.define(:kind, :type, :from, :to) do
+ def current(name)
+ return name unless applies_to?(name) && name.value == from
+ name.with(value: to)
+ end
+
+ def previous(name)
+ return name unless introduces?(name)
+ name.with(value: from)
+ end
+
+ def introduces?(name) = applies_to?(name) && name.value == to
+
+ private
+
+ def applies_to?(name) = name.kind == kind && name.type == type
+ end
+ end
+end
diff --git a/spec/fixtures/json_api_kit/api_changes/2026-09-01_rename_widgets_label_to_name.rb b/spec/fixtures/json_api_kit/api_changes/2026-09-01_rename_widgets_label_to_name.rb
new file mode 100644
index 00000000000..f5139302ece
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes/2026-09-01_rename_widgets_label_to_name.rb
@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class RenameWidgetsLabelToName < JsonApiKit::VersionChange
+ version "2026-09-01"
+ description "The `label` attribute of the widgets resource is renamed to `name`."
+
+ resource :widgets do
+ renamed_attribute from: :label, to: :name
+ end
+end
diff --git a/spec/fixtures/json_api_kit/api_changes/2026-09-02_another_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes/2026-09-02_another_widgets_change.rb
new file mode 100644
index 00000000000..9d65dafa31d
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes/2026-09-02_another_widgets_change.rb
@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class AnotherWidgetsChange < JsonApiKit::VersionChange
+ version "2026-09-02"
+ description "A later change."
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_before_first_release/2026-08-01_rename_widgets_early.rb b/spec/fixtures/json_api_kit/api_changes_before_first_release/2026-08-01_rename_widgets_early.rb
new file mode 100644
index 00000000000..80e33e4cc41
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_before_first_release/2026-08-01_rename_widgets_early.rb
@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class RenameWidgetsEarly < JsonApiKit::VersionChange
+ version "2026-08-01"
+ description "A change dated before the first release."
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_in_the_future/2099-01-01_future_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_in_the_future/2099-01-01_future_widgets_change.rb
new file mode 100644
index 00000000000..06a3254c0cd
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_in_the_future/2099-01-01_future_widgets_change.rb
@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class FutureWidgetsChange < JsonApiKit::VersionChange
+ version "2099-01-01"
+ description "A change dated in the future."
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_misdated/2026-09-01_misdated_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_misdated/2026-09-01_misdated_widgets_change.rb
new file mode 100644
index 00000000000..a86b701eda1
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_misdated/2026-09-01_misdated_widgets_change.rb
@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class MisdatedWidgetsChange < JsonApiKit::VersionChange
+ version "2026-09-02"
+ description "A change whose file name does not start with its version."
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_misnamed/2026-09-01_misnamed_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_misnamed/2026-09-01_misnamed_widgets_change.rb
new file mode 100644
index 00000000000..280f9c02c78
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_misnamed/2026-09-01_misnamed_widgets_change.rb
@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class SomeOtherWidgetsChange < JsonApiKit::VersionChange
+ version "2026-09-01"
+ description "A change whose class does not match its file."
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_with_a_bad_date/2026-09-01_bad_date_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_with_a_bad_date/2026-09-01_bad_date_widgets_change.rb
new file mode 100644
index 00000000000..e95b862326a
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_with_a_bad_date/2026-09-01_bad_date_widgets_change.rb
@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class BadDateWidgetsChange < JsonApiKit::VersionChange
+ version "01/09/2026"
+ description "A change whose version is not a date."
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_without_description/2026-09-02_undescribed_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_without_description/2026-09-02_undescribed_widgets_change.rb
new file mode 100644
index 00000000000..7dd24316468
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_without_description/2026-09-02_undescribed_widgets_change.rb
@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class UndescribedWidgetsChange < JsonApiKit::VersionChange
+ version "2026-09-02"
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_without_version/undated_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_without_version/undated_widgets_change.rb
new file mode 100644
index 00000000000..94c820a42f6
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_without_version/undated_widgets_change.rb
@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class UndatedWidgetsChange < JsonApiKit::VersionChange
+ description "A change with no version."
+end
diff --git a/spec/integration/json_api_kit/support.rb b/spec/integration/json_api_kit/support.rb
index 7717b7b2cf1..c15fa1a641d 100644
--- a/spec/integration/json_api_kit/support.rb
+++ b/spec/integration/json_api_kit/support.rb
@@ -98,7 +98,7 @@ RSpec.shared_context "with a listing of topics" do
let(:current) { "https://example.com/api/topics" }
let(:query) { {} }
let(:scoped_to) { nil }
- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }
+ let(:glossary) { JsonApiKit::Glossary.kit }
let(:urls) { JsonApiKit::Urls.new(base:, current:, parameters: query) }
let(:document) do
diff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rb
new file mode 100644
index 00000000000..5c00ea5f1ee
--- /dev/null
+++ b/spec/integration/json_api_kit/version_changes_spec.rb
@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+module JsonApiKitSpec
+ class ChangedTopicsController < JsonApiKit::BaseController
+ resource :topics
+ end
+
+ class RenameTopicsPostedAtToCreatedAt < JsonApiKit::VersionChange
+ version "2026-10-01"
+ description "The `posted_at` attribute of the topics resource is renamed to `created_at`."
+
+ resource :topics do
+ renamed_attribute from: :posted_at, to: :created_at
+ end
+ end
+end
+
+RSpec.describe "JSON:API version changes", type: :request do
+ include_context "with a listing of topics"
+
+ let(:first_version) { JsonApiKit::Timeline::FIRST_RELEASE }
+ let(:change) { JsonApiKitSpec::RenameTopicsPostedAtToCreatedAt.new(__FILE__) }
+ let(:change_version) { change.version }
+ let(:version) { first_version.to_s }
+ let(:parsed_body) { JSON.parse(response.body) }
+ let(:error) { parsed_body["errors"].sole }
+ let(:attributes) { parsed_body["data"].first["attributes"] }
+ let(:ids) { parsed_body["data"].map { it["id"] } }
+
+ before do
+ freeze_time(change_version.date + 1.day)
+ allow(JsonApiKit::VersionChange).to receive(:all).and_return([change])
+ Rails.application.routes.disable_clear_and_finalize = true
+ Rails.application.routes.draw do
+ get "/api/changed-topics" => "json_api_kit_spec/changed_topics#index"
+ end
+ Rails.application.routes.disable_clear_and_finalize = false
+ get "/api/changed-topics", headers: { "HTTP_API_VERSION" => version }, params: query
+ end
+
+ after { Rails.application.reload_routes! }
+
+ context "when the client is pinned before the change" do
+ it "sends the version of the pin" do
+ expect(response.headers["Api-Version"]).to eq(first_version.to_s)
+ end
+
+ it "sends the attributes under the names of that version" do
+ expect(attributes.keys).to contain_exactly("title", "postedAt")
+ end
+
+ context "when the request selects the renamed field" do
+ let(:query) { { "fields" => { "topics" => "postedAt" } } }
+
+ it "sends that field only" do
+ expect(attributes.keys).to contain_exactly("postedAt")
+ end
+ end
+
+ context "when the request sorts by the renamed field" do
+ let(:query) { { "sort" => "postedAt" } }
+
+ it "orders the rows by that attribute" do
+ expect(ids).to eq([oldest.id.to_s, middle.id.to_s, newest.id.to_s])
+ end
+ end
+
+ context "when the request anchors a window on the renamed field" do
+ let(:query) do
+ {
+ "sort" => "postedAt",
+ "page" => {
+ "anchor" => {
+ "postedAt" => middle.created_at.iso8601(6),
+ },
+ "beforeSize" => "1",
+ "afterSize" => "0",
+ },
+ }
+ end
+
+ it "sends the rows of the window" do
+ expect(ids).to eq([oldest.id.to_s, middle.id.to_s])
+ end
+ end
+
+ context "when a refusal includes the renamed field" do
+ let(:query) do
+ {
+ "sort" => "title",
+ "page" => {
+ "anchor" => {
+ "postedAt" => middle.created_at.iso8601(6),
+ },
+ },
+ }
+ end
+
+ it "sends the name of that version" do
+ expect(error).to eq(
+ refusal(
+ title: "Anchor does not match the sort",
+ detail: "The anchor is postedAt, but this request sorts by title.",
+ parameter: "page[anchor][postedAt]",
+ ).deep_stringify_keys,
+ )
+ end
+ end
+
+ context "when the request uses the new name" do
+ let(:query) { { "fields" => { "topics" => "createdAt" } } }
+
+ it { expect(response).to have_http_status(:bad_request) }
+
+ it "sends the reason" do
+ expect(error).to eq(
+ refusal(
+ title: "Invalid member name",
+ detail: "Use postedAt, not createdAt.",
+ parameter: "fields[topics]",
+ ).deep_stringify_keys,
+ )
+ end
+ end
+ end
+
+ context "when the client is pinned between the first version and the change" do
+ let(:version) { (first_version.date + 1.day).to_s }
+
+ it "sends the first version" do
+ expect(response.headers["Api-Version"]).to eq(first_version.to_s)
+ end
+
+ it "sends the attributes under the names of the first version" do
+ expect(attributes.keys).to contain_exactly("title", "postedAt")
+ end
+ end
+
+ context "when the client is pinned at the change" do
+ let(:version) { change_version.to_s }
+
+ it "sends the version of the change" do
+ expect(response.headers["Api-Version"]).to eq(change_version.to_s)
+ end
+
+ it "sends the attributes under the names of that version" do
+ expect(attributes.keys).to contain_exactly("title", "createdAt")
+ end
+
+ context "when the request selects the field" do
+ let(:query) { { "fields" => { "topics" => "createdAt" } } }
+
+ it "sends that field only" do
+ expect(attributes.keys).to contain_exactly("createdAt")
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/api_version_spec.rb b/spec/lib/json_api_kit/api_version_spec.rb
index b42b9b86073..324f22f9af4 100644
--- a/spec/lib/json_api_kit/api_version_spec.rb
+++ b/spec/lib/json_api_kit/api_version_spec.rb
@@ -43,6 +43,28 @@ RSpec.describe JsonApiKit::ApiVersion do
end
end
+ describe "#eql?" do
+ context "when the other version has the same date" do
+ let(:other) { described_class.parse("2026-09-01") }
+
+ it { expect(version).to eql(other) }
+ end
+
+ context "when the other version has another date" do
+ let(:other) { described_class.parse("2026-11-15") }
+
+ it { expect(version).not_to eql(other) }
+ end
+ end
+
+ describe "#hash" do
+ let(:other) { described_class.parse("2026-09-01") }
+
+ it "is the same for two versions of one date" do
+ expect(version.hash).to eq(other.hash)
+ end
+ end
+
describe "#<=>" do
context "when the other version is later" do
let(:other) { described_class.parse("2026-11-15") }
diff --git a/spec/lib/json_api_kit/document/collection_spec.rb b/spec/lib/json_api_kit/document/collection_spec.rb
index c93cf307499..9394547fbd0 100644
--- a/spec/lib/json_api_kit/document/collection_spec.rb
+++ b/spec/lib/json_api_kit/document/collection_spec.rb
@@ -3,7 +3,7 @@
RSpec.describe JsonApiKit::Document::Collection do
subject(:document) { described_class.new(listing, urls:, glossary:) }
- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }
+ let(:glossary) { JsonApiKit::Glossary.kit }
fab!(:first_topic) do
Fabricate(:topic, title: "Segments of a listing", created_at: Time.utc(2026, 8, 1))
diff --git a/spec/lib/json_api_kit/document/individual_spec.rb b/spec/lib/json_api_kit/document/individual_spec.rb
index 94f5ee6894b..935a3ee63de 100644
--- a/spec/lib/json_api_kit/document/individual_spec.rb
+++ b/spec/lib/json_api_kit/document/individual_spec.rb
@@ -3,7 +3,7 @@
RSpec.describe JsonApiKit::Document::Individual do
subject(:document) { described_class.new(reading, urls:, glossary:) }
- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }
+ let(:glossary) { JsonApiKit::Glossary.kit }
fab!(:topic) { Fabricate(:topic, title: "One record read on its own") }
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 948993bf1a7..08ad1c9726b 100644
--- a/spec/lib/json_api_kit/document/resource_object_spec.rb
+++ b/spec/lib/json_api_kit/document/resource_object_spec.rb
@@ -3,7 +3,7 @@
RSpec.describe JsonApiKit::Document::ResourceObject do
subject(:resource_object) { described_class.new(record, urls:, glossary:, meta:) }
- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }
+ let(:glossary) { JsonApiKit::Glossary.kit }
fab!(:topic) { Fabricate(:topic, title: "A row a document renders") }
diff --git a/spec/lib/json_api_kit/document_spec.rb b/spec/lib/json_api_kit/document_spec.rb
index 6c58061f589..b9747b9d069 100644
--- a/spec/lib/json_api_kit/document_spec.rb
+++ b/spec/lib/json_api_kit/document_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe JsonApiKit::Document do
end
end
let(:guardian) { Guardian.new }
- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }
+ let(:glossary) { JsonApiKit::Glossary.kit }
let(:urls) do
JsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/topics")
end
diff --git a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb b/spec/lib/json_api_kit/glossary/casing_rule_spec.rb
index 124ed1c60d8..9e858cc031a 100644
--- a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb
+++ b/spec/lib/json_api_kit/glossary/casing_rule_spec.rb
@@ -1,70 +1,86 @@
# frozen_string_literal: true
RSpec.describe JsonApiKit::Glossary::CasingRule do
- subject(:rule) { described_class }
+ let(:rule) { described_class }
+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
+ let(:value) { "createdAt" }
describe "#declared_name" do
+ subject(:declared_name) { rule.declared_name(name) }
+
it "returns the name in snake case" do
- expect(rule.declared_name("createdAt")).to eq("created_at")
+ expect(declared_name).to eq(name.with(value: "created_at"))
end
context "when the value is a list of names" do
+ let(:name) { JsonApiKit::Name::Member.new(value: "-createdAt,title") }
+
it "returns every name in snake case" do
- expect(rule.declared_name("-createdAt,title")).to eq("-created_at,title")
+ expect(declared_name).to eq(name.with(value: "-created_at,title"))
end
end
context "when the value is a path" do
+ let(:name) { JsonApiKit::Name::Member.new(value: "solvedStatus.answeredAt") }
+
it "returns every segment" do
- expect(rule.declared_name("solvedStatus.answeredAt")).to eq("solved_status.answered_at")
+ expect(declared_name).to eq(name.with(value: "solved_status.answered_at"))
end
end
context "when the name has a hyphen" do
+ let(:name) { JsonApiKit::Name::Member.new(value: "solved-statuses") }
+
it "keeps the hyphen" do
- expect(rule.declared_name("solved-statuses")).to eq("solved-statuses")
+ expect(declared_name).to eq(name)
end
end
context "when the name starts with a capital" do
- it do
- expect { rule.declared_name("CreatedAt") }.to raise_error(described_class::NotAMemberName)
- end
+ let(:value) { "CreatedAt" }
+
+ it { expect { declared_name }.to raise_error(JsonApiKit::Glossary::Correction) }
end
context "when the name ends with capitals" do
- it do
- expect { rule.declared_name("createdAT") }.to raise_error(described_class::NotAMemberName)
- end
+ let(:value) { "createdAT" }
+
+ it { expect { declared_name }.to raise_error(JsonApiKit::Glossary::Correction) }
end
context "when the name has an underscore" do
- it do
- expect { rule.declared_name("created_at") }.to raise_error(described_class::NotAMemberName)
- end
+ let(:value) { "created_at" }
- it "suggests the name to use instead" do
- expect { rule.declared_name("created_at") }.to raise_error(
- /Use createdAt, not created_at\./,
- )
+ it { expect { declared_name }.to raise_error(JsonApiKit::Glossary::Correction) }
+
+ it "raises a correction with the name in snake case" do
+ expect { declared_name }.to raise_error(having_attributes(name:))
end
end
end
describe "#member_name" do
+ subject(:member_name) { rule.member_name(name) }
+
+ let(:value) { "created_at" }
+
it "returns the name in camel case" do
- expect(rule.member_name("created_at")).to eq("createdAt")
+ expect(member_name).to eq(name.with(value: "createdAt"))
end
context "when the name is a path" do
+ let(:name) { JsonApiKit::Name::Member.new(value: "last_poster.last_seen_at") }
+
it "returns every segment" do
- expect(rule.member_name("last_poster.last_seen_at")).to eq("lastPoster.lastSeenAt")
+ expect(member_name).to eq(name.with(value: "lastPoster.lastSeenAt"))
end
end
context "when the name has a hyphen" do
+ let(:name) { JsonApiKit::Name::Member.new(value: "solved-statuses") }
+
it "keeps the hyphen" do
- expect(rule.member_name("solved-statuses")).to eq("solved-statuses")
+ expect(member_name).to eq(name)
end
end
end
diff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
new file mode 100644
index 00000000000..b3e9a53b532
--- /dev/null
+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module JsonApiKitSpec
+ class FirstRuleChange < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "The first change."
+
+ resource :topics do
+ renamed_attribute from: :posted_at, to: :created_at
+ end
+ end
+
+ class SecondRuleChange < JsonApiKit::VersionChange
+ version "2026-10-01"
+ description "The second change."
+
+ resource :topics do
+ renamed_attribute from: :created_at, to: :published_at
+ end
+ end
+
+ class NameToTitleChange < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "The `name` attribute of the topics resource is renamed to `title`."
+
+ resource :topics do
+ renamed_attribute from: :name, to: :title
+ end
+ end
+
+ class LabelToNameChange < JsonApiKit::VersionChange
+ version "2026-10-01"
+ description "The `label` attribute of the topics resource is renamed to `name`."
+
+ resource :topics do
+ renamed_attribute from: :label, to: :name
+ end
+ end
+end
+
+RSpec.describe JsonApiKit::Glossary::VersionRule do
+ subject(:rule) { described_class.new(version) }
+
+ let(:version) { JsonApiKit::ApiVersion.parse("2026-09-01") }
+ let(:first_change) { JsonApiKitSpec::FirstRuleChange.new(__FILE__) }
+ let(:second_change) { JsonApiKitSpec::SecondRuleChange.new(__FILE__) }
+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
+ let(:value) { "posted_at" }
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ [first_change, second_change],
+ )
+ end
+
+ describe "#declared_name" do
+ subject(:declared_name) { rule.declared_name(name) }
+
+ it "returns the current name of an old name" do
+ expect(declared_name).to eq(name.with(value: "published_at"))
+ end
+
+ context "when a later change reuses a spelling of this version" do
+ let(:first_change) { JsonApiKitSpec::NameToTitleChange.new(__FILE__) }
+ let(:second_change) { JsonApiKitSpec::LabelToNameChange.new(__FILE__) }
+ let(:value) { "name" }
+
+ it "returns the current name of the old name" do
+ expect(declared_name).to eq(name.with(value: "title"))
+ end
+
+ context "when the name belongs to a later version" do
+ let(:value) { "title" }
+
+ it "raises a correction with the declared name" do
+ expect { declared_name }.to raise_error(having_attributes(name:))
+ end
+ end
+ end
+
+ context "when no change touches the name" do
+ let(:value) { "title" }
+
+ it "returns the name" do
+ expect(declared_name).to eq(name)
+ end
+ end
+
+ context "when the name belongs to a later version" do
+ let(:value) { "published_at" }
+
+ it "raises a correction with the declared name" do
+ expect { declared_name }.to raise_error(
+ an_instance_of(JsonApiKit::Glossary::Correction).and(having_attributes(name:)),
+ )
+ end
+ end
+ end
+
+ describe "#member_name" do
+ subject(:member_name) { rule.member_name(name) }
+
+ let(:value) { "published_at" }
+
+ it "returns the name of this version for a current name" do
+ expect(member_name).to eq(name.with(value: "posted_at"))
+ end
+
+ context "when no change touches the name" do
+ let(:value) { "title" }
+
+ it "returns the name" do
+ expect(member_name).to eq(name)
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rb
index 4b7431bf01f..bdd76d2f148 100644
--- a/spec/lib/json_api_kit/glossary_spec.rb
+++ b/spec/lib/json_api_kit/glossary_spec.rb
@@ -3,14 +3,37 @@
module JsonApiKitSpec
MarkingRule =
Struct.new(:mark) do
- def declared_name(name) = "#{name}<#{mark}"
+ def declared_name(name) = name.convert { "#{it}<#{mark}" }
- def member_name(name) = "#{name}>#{mark}"
+ def member_name(name) = name.convert { "#{it}>#{mark}" }
end
+
+ class GlossaryChange < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "The `posted_at` attribute of the topics resource is renamed to `created_at`."
+
+ resource :topics do
+ renamed_attribute from: :posted_at, to: :created_at
+ end
+ end
+
+ class GlossaryReuseChange < JsonApiKit::VersionChange
+ version "2026-10-01"
+ description "The `label` attribute of the topics resource is renamed to `posted_at`."
+
+ resource :topics do
+ renamed_attribute from: :label, to: :posted_at
+ end
+ end
end
RSpec.describe JsonApiKit::Glossary do
- subject(:glossary) { described_class.new([JsonApiKit::Glossary::CasingRule]) }
+ subject(:glossary) { described_class.new([described_class::CasingRule]) }
+
+ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }
+ let(:change) { JsonApiKitSpec::GlossaryChange.new(__FILE__) }
+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
+ let(:value) { "createdAt" }
describe ".kit" do
subject(:kit) { described_class.kit }
@@ -19,24 +42,92 @@ RSpec.describe JsonApiKit::Glossary do
it "builds a glossary with the wire format rules" do
kit
- expect(described_class).to have_received(:new).with([JsonApiKit::Glossary::CasingRule])
+ expect(described_class).to have_received(:new).with([described_class::CasingRule])
end
end
describe ".resource" do
- subject(:resource) { described_class.resource }
+ subject(:resource) { described_class.resource(version) }
- before { allow(described_class).to receive(:new).and_call_original }
+ before do
+ allow(described_class).to receive(:new).and_call_original
+ allow(described_class::VersionRule).to receive(:new).and_call_original
+ end
- it "builds a glossary with the rules for a resource" do
+ it "builds a glossary with the wire format rules and the version rule" do
resource
- expect(described_class).to have_received(:new).with([JsonApiKit::Glossary::CasingRule])
+ expect(described_class).to have_received(:new).with(
+ [described_class::CasingRule, an_instance_of(described_class::VersionRule)],
+ )
+ end
+
+ it "builds the version rule for the version" do
+ resource
+ expect(described_class::VersionRule).to have_received(:new).with(version)
end
end
describe "#declared_name" do
+ subject(:declared_name) { glossary.declared_name(name) }
+
it "returns the declared name" do
- expect(glossary.declared_name("createdAt")).to eq("created_at")
+ expect(declared_name).to eq(name.with(value: "created_at"))
+ end
+
+ context "when the name is not a member name" do
+ let(:value) { "created_at" }
+
+ it "raises a refusal" do
+ expect { declared_name }.to raise_error(described_class::NotAMemberName)
+ end
+
+ it "suggests the name to use instead" do
+ expect { declared_name }.to raise_error(/Use createdAt, not created_at\./)
+ end
+ end
+
+ context "with a version rule" do
+ subject(:glossary) { described_class.resource(version) }
+
+ let(:value) { "postedAt" }
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])
+ end
+
+ it "returns the current name" do
+ expect(declared_name).to eq(name.with(value: "created_at"))
+ end
+
+ context "when the name belongs to a later version" do
+ let(:value) { "createdAt" }
+
+ it "suggests the name of this version, on the wire" do
+ expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)
+ end
+ end
+
+ context "when the name is in snake case" do
+ let(:value) { "created_at" }
+
+ it "suggests the name of this version, on the wire" do
+ expect { declared_name }.to raise_error(/Use postedAt, not created_at\./)
+ end
+ end
+
+ context "when a later change reuses a spelling of this version" do
+ let(:value) { "createdAt" }
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ [change, JsonApiKitSpec::GlossaryReuseChange.new(__FILE__)],
+ )
+ end
+
+ it "suggests the name of this version, converted once" do
+ expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)
+ end
+ end
end
context "with several rules" do
@@ -46,14 +137,30 @@ RSpec.describe JsonApiKit::Glossary do
let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
it "applies them in order" do
- expect(glossary.declared_name("x")).to eq("x<a<b")
+ expect(declared_name).to eq(name.with(value: "createdAt<a<b"))
end
end
end
describe "#member_name" do
+ subject(:member_name) { glossary.member_name(name) }
+
+ let(:value) { "created_at" }
+
it "returns the member name" do
- expect(glossary.member_name("created_at")).to eq("createdAt")
+ expect(member_name).to eq(name.with(value: "createdAt"))
+ 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([change])
+ end
+
+ it "returns the name of this version, on the wire" do
+ expect(member_name).to eq(name.with(value: "postedAt"))
+ end
end
context "with several rules" do
@@ -63,7 +170,7 @@ RSpec.describe JsonApiKit::Glossary do
let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
it "applies them in reverse order" do
- expect(glossary.member_name("x")).to eq("x>b>a")
+ expect(member_name).to eq(name.with(value: "created_at>b>a"))
end
end
end
diff --git a/spec/lib/json_api_kit/name/anchor_spec.rb b/spec/lib/json_api_kit/name/anchor_spec.rb
new file mode 100644
index 00000000000..c39281f6399
--- /dev/null
+++ b/spec/lib/json_api_kit/name/anchor_spec.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+RSpec.describe JsonApiKit::Name::Anchor do
+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }
+
+ it_behaves_like "a name", :anchor
+end
diff --git a/spec/lib/json_api_kit/name/field_spec.rb b/spec/lib/json_api_kit/name/field_spec.rb
new file mode 100644
index 00000000000..e3b30d135a7
--- /dev/null
+++ b/spec/lib/json_api_kit/name/field_spec.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+RSpec.describe JsonApiKit::Name::Field do
+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }
+
+ it_behaves_like "a name", :field
+end
diff --git a/spec/lib/json_api_kit/name/filter_spec.rb b/spec/lib/json_api_kit/name/filter_spec.rb
new file mode 100644
index 00000000000..ac22a60d0f5
--- /dev/null
+++ b/spec/lib/json_api_kit/name/filter_spec.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+RSpec.describe JsonApiKit::Name::Filter do
+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }
+
+ it_behaves_like "a name", :filter
+end
diff --git a/spec/lib/json_api_kit/name/member_spec.rb b/spec/lib/json_api_kit/name/member_spec.rb
new file mode 100644
index 00000000000..1ca32cff057
--- /dev/null
+++ b/spec/lib/json_api_kit/name/member_spec.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+RSpec.describe JsonApiKit::Name::Member do
+ subject(:name) { described_class.new(value: "after_size") }
+
+ it_behaves_like "a name", :member
+end
diff --git a/spec/lib/json_api_kit/name/relationship_spec.rb b/spec/lib/json_api_kit/name/relationship_spec.rb
new file mode 100644
index 00000000000..8d41e7517ed
--- /dev/null
+++ b/spec/lib/json_api_kit/name/relationship_spec.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+RSpec.describe JsonApiKit::Name::Relationship do
+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }
+
+ it_behaves_like "a name", :relationship
+end
diff --git a/spec/lib/json_api_kit/name/sort_spec.rb b/spec/lib/json_api_kit/name/sort_spec.rb
new file mode 100644
index 00000000000..79ec71ca4cc
--- /dev/null
+++ b/spec/lib/json_api_kit/name/sort_spec.rb
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+RSpec.describe JsonApiKit::Name::Sort do
+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }
+
+ it_behaves_like "a name", :sort
+end
diff --git a/spec/lib/json_api_kit/name/support.rb b/spec/lib/json_api_kit/name/support.rb
new file mode 100644
index 00000000000..5148140a637
--- /dev/null
+++ b/spec/lib/json_api_kit/name/support.rb
@@ -0,0 +1,21 @@
+# 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
+
+ describe "#convert" do
+ it "returns the name with the converted value" do
+ expect(name.convert(&:upcase)).to eq(name.with(value: name.value.upcase))
+ end
+ end
+
+ describe "#to_s" do
+ it "returns the value" do
+ expect(name.to_s).to eq(name.value)
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/request/contract/collection_spec.rb b/spec/lib/json_api_kit/request/contract/collection_spec.rb
index e5c072ef018..697dead9842 100644
--- a/spec/lib/json_api_kit/request/contract/collection_spec.rb
+++ b/spec/lib/json_api_kit/request/contract/collection_spec.rb
@@ -69,6 +69,18 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
it { is_expected.not_to allow_value("secrets", "created_at,secrets").for(:sort) }
it { is_expected.not_to allow_value(%w[created_at], 5).for(:sort) }
+ context "when a sort is unknown" do
+ let(:params) { { sort: { posted_at: :asc } } }
+
+ before { contract.valid? }
+
+ it "adds an error with the sort name of the resource" do
+ expect(contract.errors.where(:sort, :no_such_name).sole.options[:name]).to eq(
+ JsonApiKit::Name::Sort.new(value: "posted_at", type: "topics"),
+ )
+ end
+ end
+
context "when sort is a string" do
let(:params) { { sort: "-created_at,title" } }
@@ -162,6 +174,17 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
before { contract.valid? }
+ context "when the anchor is not the sort" do
+ let(:params) { { sort: { created_at: :asc }, page: { anchor: { title: "A" } } } }
+
+ it "adds an error with the anchor name and the sort name of the resource" do
+ expect(contract.errors.where(:"page.anchor", :not_the_sort).sole.options).to include(
+ name: JsonApiKit::Name::Anchor.new(value: "title", type: "topics"),
+ key: JsonApiKit::Name::Sort.new(value: "created_at", type: "topics"),
+ )
+ end
+ end
+
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) }
diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rb
index 81f240331a3..8c24a2bee96 100644
--- a/spec/lib/json_api_kit/request/parameters_spec.rb
+++ b/spec/lib/json_api_kit/request/parameters_spec.rb
@@ -1,9 +1,30 @@
# frozen_string_literal: true
+module JsonApiKitSpec
+ class ParametersResource < JsonApiKit::Resource
+ type :topics
+ end
+
+ class ParametersChange < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "Two resources rename a field."
+
+ resource :topics do
+ renamed_attribute from: :posted_at, to: :created_at
+ end
+
+ resource :users do
+ renamed_attribute from: :handle, to: :username
+ end
+ end
+end
+
RSpec.describe JsonApiKit::Request::Parameters do
- subject(:declared_parameters) { described_class.new(parameters, glossary:).to_h }
+ subject(:declared_parameters) do
+ described_class.new(parameters, glossary:, resource: JsonApiKitSpec::ParametersResource).to_h
+ end
- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }
+ let(:glossary) { JsonApiKit::Glossary.kit }
let(:parameters) { { "sort" => "-createdAt" } }
it "converts the sort names" do
@@ -52,7 +73,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
it "raises with the parameter that holds it" do
expect { declared_parameters }.to raise_error(
- an_instance_of(JsonApiKit::Glossary::CasingRule::NotAMemberName).and(
+ an_instance_of(JsonApiKit::Glossary::NotAMemberName).and(
having_attributes(source: { parameter: "sort" }),
),
)
@@ -69,6 +90,86 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
end
+ context "with a version change" do
+ let(:glossary) { JsonApiKit::Glossary.resource(version) }
+ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }
+ let(:change) { JsonApiKitSpec::ParametersChange.new(__FILE__) }
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])
+ end
+
+ context "when a fieldset has a renamed field" do
+ let(:parameters) { { "fields" => { "topics" => "postedAt" } } }
+
+ it "converts the field to its current name" do
+ expect(declared_parameters).to eq("fields" => { "topics" => "created_at" })
+ end
+ end
+
+ context "when a fieldset of another type has a renamed field" do
+ let(:parameters) { { "fields" => { "users" => "handle" } } }
+
+ it "converts the field with the names of that type" do
+ expect(declared_parameters).to eq("fields" => { "users" => "username" })
+ end
+ end
+
+ context "when the sort has a renamed field" do
+ let(:parameters) { { "sort" => "-postedAt" } }
+
+ it "converts the field to its current name" do
+ expect(declared_parameters).to eq("sort" => "-created_at")
+ end
+ end
+
+ context "when the sort has several fields" do
+ let(:parameters) { { "sort" => "-postedAt,title" } }
+
+ it "converts every field" do
+ expect(declared_parameters).to eq("sort" => "-created_at,title")
+ end
+ end
+
+ context "when a fieldset has several fields" do
+ let(:parameters) { { "fields" => { "topics" => "title,postedAt" } } }
+
+ it "converts every field" do
+ expect(declared_parameters).to eq("fields" => { "topics" => "title,created_at" })
+ end
+ end
+
+ context "when the anchor has a renamed field" do
+ let(:parameters) { { "page" => { "anchor" => { "postedAt" => "2026-08-01" } } } }
+
+ it "converts the field to its current name" do
+ expect(declared_parameters).to eq(
+ "page" => {
+ "anchor" => {
+ "created_at" => "2026-08-01",
+ },
+ },
+ )
+ end
+ end
+
+ context "when a filter has the name of a renamed field" do
+ let(:parameters) { { "filter" => { "postedAt" => "2026-08-01" } } }
+
+ it "converts the case of the filter name only" do
+ expect(declared_parameters).to eq("filter" => { "posted_at" => "2026-08-01" })
+ end
+ end
+ end
+
+ context "when a name has a newline" do
+ let(:parameters) { { "sort" => "createdAt\n" } }
+
+ it "converts the case and keeps the newline for the contract" do
+ expect(declared_parameters).to eq("sort" => "created_at\n")
+ end
+ end
+
context "when the parameters have a filter" do
let(:parameters) { { "filter" => { "postCount" => "SomeTopic Title" } } }
diff --git a/spec/lib/json_api_kit/timeline_spec.rb b/spec/lib/json_api_kit/timeline_spec.rb
index cc214ef4369..ca8878a0d6f 100644
--- a/spec/lib/json_api_kit/timeline_spec.rb
+++ b/spec/lib/json_api_kit/timeline_spec.rb
@@ -1,26 +1,50 @@
# frozen_string_literal: true
+module JsonApiKitSpec
+ class MiddleTimelineChange < JsonApiKit::VersionChange
+ version "2026-11-15"
+ description "The middle change on the timeline."
+ end
+
+ class LatestTimelineChange < JsonApiKit::VersionChange
+ version "2027-01-05"
+ description "The latest change on the timeline."
+ end
+end
+
RSpec.describe JsonApiKit::Timeline do
- let(:earliest) { JsonApiKit::ApiVersion.parse("2026-09-01") }
+ let(:first) { described_class::FIRST_RELEASE }
let(:middle) { JsonApiKit::ApiVersion.parse("2026-11-15") }
let(:latest) { JsonApiKit::ApiVersion.parse("2027-01-05") }
- let(:timeline) { described_class.new([earliest, middle, latest]) }
before do
freeze_time(Date.new(2027, 1, 20))
- allow(described_class).to receive(:core).and_return(timeline)
+ allow(JsonApiKit::VersionChange).to receive(:all).and_return(
+ [
+ JsonApiKitSpec::MiddleTimelineChange.new(__FILE__),
+ JsonApiKitSpec::LatestTimelineChange.new(__FILE__),
+ ],
+ )
end
describe ".first" do
- it "returns the earliest version" do
- expect(described_class.first).to eq(earliest)
+ it "returns the first release" do
+ expect(described_class.first).to eq(first)
end
end
describe ".current" do
- it "returns the latest version" do
+ it "returns the version of the latest change" do
expect(described_class.current).to eq(latest)
end
+
+ context "when there is no change" do
+ before { allow(JsonApiKit::VersionChange).to receive(:all).and_return([]) }
+
+ it "returns the first release" do
+ expect(described_class.current).to eq(first)
+ end
+ end
end
describe ".resolve" do
@@ -57,7 +81,7 @@ RSpec.describe JsonApiKit::Timeline do
end
context "when the date is earlier than the first version" do
- let(:raw) { (earliest.date - 1.day).to_s }
+ let(:raw) { (first.date - 1.day).to_s }
it { expect { version }.to raise_error(JsonApiKit::ApiVersion::Unknown) }
end
diff --git a/spec/lib/json_api_kit/version_change/rename_spec.rb b/spec/lib/json_api_kit/version_change/rename_spec.rb
new file mode 100644
index 00000000000..101d03dce6b
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change/rename_spec.rb
@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChange::Rename do
+ subject(:rename) do
+ described_class.new(kind: :field, type: "topics", from: "posted_at", to: "created_at")
+ end
+
+ 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)
+ end
+
+ context "when the name is of another kind" do
+ let(:old_name) { JsonApiKit::Name::Sort.new(value: "posted_at", type: "topics") }
+
+ it "returns the name" do
+ expect(rename.current(old_name)).to eq(old_name)
+ end
+ end
+
+ context "when the name is of another type" do
+ let(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "users") }
+
+ it "returns the name" do
+ expect(rename.current(old_name)).to eq(old_name)
+ end
+ end
+ end
+
+ describe "#previous" do
+ it "returns the old name for the new one" do
+ expect(rename.previous(new_name)).to eq(old_name)
+ end
+
+ context "when the name is of another kind" do
+ let(:new_name) { JsonApiKit::Name::Sort.new(value: "created_at", type: "topics") }
+
+ it "returns the name" do
+ expect(rename.previous(new_name)).to eq(new_name)
+ end
+ end
+
+ context "when the name is of another type" do
+ let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "users") }
+
+ it "returns the name" do
+ expect(rename.previous(new_name)).to eq(new_name)
+ end
+ end
+ end
+
+ describe "#introduces?" do
+ it { expect(rename).to be_introduces(new_name) }
+ it { expect(rename).not_to be_introduces(old_name) }
+ end
+end
diff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rb
new file mode 100644
index 00000000000..efbd87b2661
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change_spec.rb
@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module JsonApiKitSpec
+ class RenameThingsLabelToName < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "The `label` attribute of the things resource is renamed to `name`."
+
+ resource :things do
+ renamed_attribute from: :label, to: :name
+ end
+ end
+
+ class RenameThingsAndPeople < JsonApiKit::VersionChange
+ version "2026-10-01"
+ description "Two resources change their names."
+
+ resource :things do
+ renamed_attribute from: :label, to: :name
+ end
+
+ resource :people do
+ renamed_attribute from: :handle, to: :username
+ end
+ end
+end
+
+RSpec.describe JsonApiKit::VersionChange do
+ subject(:change) { JsonApiKitSpec::RenameThingsLabelToName.new(__FILE__) }
+
+ 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") }
+ let(:name) { JsonApiKit::Name::Field.new(value: "label", type: "things") }
+
+ describe ".read" do
+ subject(:changes) { described_class.read(fixtures.join(directory)) }
+
+ let(:directory) { "api_changes" }
+
+ it "returns the change of each file, oldest version first" do
+ expect(changes.map(&:class)).to eq([RenameWidgetsLabelToName, AnotherWidgetsChange])
+ end
+
+ it "gives each change the file it came from" do
+ expect(changes.first.source.to_s).to end_with("2026-09-01_rename_widgets_label_to_name.rb")
+ end
+
+ context "when the file name does not start with the version" do
+ let(:directory) { "api_changes_misdated" }
+
+ it do
+ expect { changes }.to raise_error(ArgumentError, /must start with the version 2026-09-02/)
+ end
+ end
+
+ context "when a change is dated in the future" do
+ let(:directory) { "api_changes_in_the_future" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /in the future/) }
+ end
+
+ context "when the version of a change is not a date" do
+ let(:directory) { "api_changes_with_a_bad_date" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /is not a date/) }
+ end
+
+ context "when the class of a change does not match its file" do
+ let(:directory) { "api_changes_misnamed" }
+
+ it { expect { changes }.to raise_error(NameError, /MisnamedWidgetsChange/) }
+ end
+
+ context "when a change has no version" do
+ let(:directory) { "api_changes_without_version" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /has no version/) }
+ end
+
+ context "when a change is dated on or before the first release" do
+ let(:directory) { "api_changes_before_first_release" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /on or before the first release/) }
+ end
+
+ context "when a change has no description" do
+ let(:directory) { "api_changes_without_description" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /has no description/) }
+ end
+ end
+
+ describe ".after" do
+ subject(:changes) { described_class.after(pin) }
+
+ let(:pin) { version }
+ let(:later_change) { JsonApiKitSpec::RenameThingsAndPeople.new(__FILE__) }
+
+ before { allow(described_class).to receive(:all).and_return([change, later_change]) }
+
+ it "returns the changes dated after the version" do
+ expect(changes).to eq([later_change])
+ end
+
+ context "when the version is the latest" do
+ let(:pin) { later_version }
+
+ it "returns no change" do
+ expect(changes).to be_empty
+ end
+ end
+ end
+
+ describe "#version" do
+ it "returns the version of the change" do
+ expect(change.version).to eq(version)
+ end
+ end
+
+ describe "#description" do
+ it "returns the description of the change" do
+ expect(change.description).to eq(
+ "The `label` attribute of the things resource is renamed to `name`.",
+ )
+ end
+ end
+
+ describe "#current" do
+ subject(:current_name) { change.current(name) }
+
+ it "returns the name after the change" do
+ expect(current_name).to eq(name.with(value: "name"))
+ end
+
+ context "when the name is the sort derived from the attribute" do
+ let(:name) { JsonApiKit::Name::Sort.new(value: "label", type: "things") }
+
+ it "renames it" do
+ expect(current_name).to eq(name.with(value: "name"))
+ end
+ end
+
+ context "when the name is the anchor derived from the attribute" do
+ let(:name) { JsonApiKit::Name::Anchor.new(value: "label", type: "things") }
+
+ it "renames it" do
+ expect(current_name).to eq(name.with(value: "name"))
+ end
+ end
+
+ context "when the name is a filter with that name" do
+ let(:name) { JsonApiKit::Name::Filter.new(value: "label", type: "things") }
+
+ it "returns the name" do
+ expect(current_name).to eq(name)
+ end
+ end
+
+ context "with several resources" do
+ subject(:change) { JsonApiKitSpec::RenameThingsAndPeople.new(__FILE__) }
+
+ let(:other_name) { JsonApiKit::Name::Field.new(value: "handle", type: "people") }
+
+ it "renames the names of every resource" do
+ expect([change.current(name), change.current(other_name)]).to eq(
+ [name.with(value: "name"), other_name.with(value: "username")],
+ )
+ end
+ end
+ end
+
+ describe "#previous" do
+ subject(:previous_name) { change.previous(name) }
+
+ let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
+
+ it "returns the name before the change" do
+ expect(previous_name).to eq(name.with(value: "label"))
+ end
+ end
+
+ describe "#introduces?" do
+ context "when the change renames another name to this one" do
+ let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
+
+ it { expect(change).to be_introduces(name) }
+ end
+
+ context "when the change renames this name away" do
+ it { expect(change).not_to be_introduces(name) }
+ end
+ end
+end
diff --git a/spec/resources/group_resource_spec.rb b/spec/resources/group_resource_spec.rb
index ed399c4e189..f1055de249d 100644
--- a/spec/resources/group_resource_spec.rb
+++ b/spec/resources/group_resource_spec.rb
@@ -4,7 +4,7 @@ RSpec.describe GroupResource do
fab!(:group) { Fabricate(:group, name: "a_group") }
let(:guardian) { Guardian.new }
- let(:glossary) { JsonApiKit::Glossary.resource }
+ let(:glossary) { JsonApiKit::Glossary.kit }
let(:urls) do
JsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/groups")
end
diff --git a/spec/resources/user_resource_spec.rb b/spec/resources/user_resource_spec.rb
index 7280d3f9bc3..d03631fcd89 100644
--- a/spec/resources/user_resource_spec.rb
+++ b/spec/resources/user_resource_spec.rb
@@ -4,7 +4,7 @@ RSpec.describe UserResource do
fab!(:user) { Fabricate(:user, username: "someone") }
let(:guardian) { Guardian.new }
- let(:glossary) { JsonApiKit::Glossary.resource }
+ let(:glossary) { JsonApiKit::Glossary.kit }
let(:urls) do
JsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/users")
end