jpie 3.11.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc59c786e140082618fccd88462e9ea9e3c98d97aa6184752d9d06b0c99d8eb
-  data.tar.gz: 4e212599caf45aad70ba6f286a2be35e5d61df0aee6c62e23f3177f827e7bb83
+  metadata.gz: fd3d3cf0f731b0a5d47d2e0ae3b4fc405d7b49ae775da39baf04a3f862b06d3b
+  data.tar.gz: 2d305cd5e41bb20cc5ef36fdf0321407425e503fee2a7424f40035cb9fda0059
 SHA512:
-  metadata.gz: 2360e7d99ce16c2e9a9b485920811cd56f69e6281cd2dfd5b565be44a23c6cea9f9b85f8bd23caabe45b8e8976ff67e650d43bdc3a49ca9de1aab75151dc33db
-  data.tar.gz: 29f4244ee319f9a68403f4aeda3f8a497b843c5b67e0cd975704bc5e3f9ac0c4041da86fc008c618ca4552c08b3f167eb6794ae36adc7ad4b14095ec6e3bc7b9
+  metadata.gz: beeb386f1743ca01b78a5532925d16115b66ca94ae00f31b1b94118c7b0bdf63367e00242593b78e62cd891c7e497cc00b722ee17d6fa37b724f2de5aa40d178
+  data.tar.gz: e6362ed9996bec7dedabf0891e9a50a4ff80f240829cf6f7e08decf4b4ddf5d29c139f6e71eb88de1a53648449c416907a81c7f73dee1134e49a4b8704ca5063

data/CHANGELOG.md

@@ -7,6 +7,133 @@ at release time.
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-09-09
+
+### Changed
+
+- **Breaking. A namespace serves only what it declares.** A namespaced request
+  used to fall back to the flat resource when the namespaced one was missing —
+  for the primary type, and for every `?include=` hop. On a public namespace
+  that published the internal resource's records and attributes to an
+  anonymous caller, and an STI record slipped to its base class's flat
+  resource even where the namespace carried a base resource. The fallback is
+  gone, and `config.namespace_fallback` with it. A namespaced request resolves
+  the namespaced resource alone. A route whose namespace carries no resource
+  fails at draw time — the app does not boot — because `jsonapi_resources`
+  resolves the resource while routes load. An include hop the namespace
+  cannot answer is a 400 at validation, before the record loads; a
+  polymorphic hop, which validation cannot judge, answers 400 (or 404 on a
+  relationships route) when a record's class resolves nothing at
+  serialization. A namespaced model still
+  reaches the resource in its own namespace, and an STI record answers
+  through the request namespace's resource for its own class, then its base
+  class. To keep serving a flat resource inside a namespace, declare it:
+  `class API::V1::WidgetResource < WidgetResource; end`. That line is the
+  audit trail. Release this as a major version.
+
+  The relationships routes obey the same rule: the linkage and related-record
+  scopes resolve through the request namespace's resource, where they used to
+  resolve with no namespace at all. Write-path linkage lookups (deserializing
+  a relationship's resource identifiers) still resolve without a namespace;
+  a bound write surface gates those through its declared field lists.
+- Read the outer hash when neither it nor its `data` member names a `type`.
+  `JSONAPI::Deserializer.new(data: { attributes: { … } })` used to read the
+  nested member; it now reads the outer hash and finds no attributes. Such a
+  hash is neither a document nor a resource object, because JSON:API requires
+  `type` in every resource object. Name the `type` to keep the old result.
+- Answer `{}` instead of raising `TypeError` for a document whose `data` member
+  holds an array. `dig(:data, :attributes)` raised on the array.
+- Read a declared write list as the complete allow-list for relationships. jpie
+  gated a relationship only when the resource named it in `creatable_fields` or
+  `updatable_fields`. A relationship named in neither stayed writable, so a
+  resource that declared an allow-list of attributes still accepted any
+  relationship the client sent. The client re-pointed a row it did not own. A
+  resource that declares the list for an action now refuses a relationship the
+  list omits.
+
+  This refuses writes jpie used to accept. Check every resource that calls
+  `creatable_fields` or `updatable_fields` and names no relationship, and every
+  subclass of one, because a subclass that declares nothing reads its parent's
+  lists. A client that writes a relationship on such a resource now meets 403
+  Forbidden. Name the relationship in the list to keep the write.
+
+  Two shapes are unaffected. A resource that declares no list falls back to the
+  attribute list, which names no relationship, so failing closed there would
+  refuse every resource that never stated an opinion. An override of
+  `permitted_creatable_fields` or `permitted_updatable_fields` is not a
+  declaration either: an override that adjusts the inherited list, such as
+  `super - [:role]`, returns a plain array, the same as one that states a fresh
+  list, so jpie cannot tell the two apart. On both shapes, `readonly: true`
+  still stops a write.
+- **Breaking. Cut the public API.** Hold a relationship route to the `only:`
+  and `except:` the caller gives `jsonapi_resources`. Each verb stands on a
+  member action: `GET` on `:show`, and `PATCH` and `DELETE` both on
+  `:update` — a relationship `DELETE` removes members from the relationship,
+  the controller authorizes it as an update, and the primary record survives,
+  so `:destroy` plays no part. Before this, `only:` cut the member routes and
+  left all three relationship routes whole, so a caller who omitted `:update`
+  still got `PATCH /:type/:id/relationships/:relationship_name`. The
+  relationships controller authorizes the parent record alone, so the omitted
+  member action did no work there and the write landed. The base route of an
+  `sti:` set carries `only: :index`, so it now draws no relationship route.
+  The `:relationship` path helper hangs on the first verb drawn, so it
+  survives without `:show`. Release this as a major version.
+
+  An STI subtype route that states no options of its own now inherits the
+  caller's `only:`/`except:` as well — auto-drawn subtypes and bare explicit
+  entries used to draw every route whatever the caller restricted. A hash
+  subtype entry keeps its own declaration.
+
+  Regenerate the OpenAPI document with the route audit: a consumer that
+  documents relationship routes carries phantom operations for every verb
+  this removes.
+
+  Audit every `jsonapi_resources` line before the bump: a declaration without
+  `:update` loses relationship `PATCH` and `DELETE`, and one without `:show`
+  loses relationship `GET`. Measured against kiln's route table, 60 of 112
+  declarations lose at least one relationship verb — most of them read-only
+  template, suggestion, and public-portal surfaces, which is the point of the
+  change. A caller who wants a relationship verb back must name its member
+  action.
+- Skip strictly less with `skip_before_action :load_jsonapi_resource`: the
+  callback now loads the record alone, so a controller that skips it still
+  resolves the resource class and still validates `include`, `fields` and
+  `filter`. On a typed route a bad `include` answers 400 where it used to
+  raise over a nil resource class.
+- Answer 404, not a NoMethodError 500, for a hand-drawn route whose resource
+  type resolves to no class — the same answer the relationships controller
+  already gives. `jsonapi_resources` resolves the resource at draw time, so
+  only a hand-drawn route reaches this.
+- Validate `include`, `fields` and `filter` before the record loads. The loader
+  ran first and built its query from the client's `include`, so a path the gem
+  then rejected with 400 had already read the record and preloaded every hop.
+  A `show` with `include=posts.comments.invalid_association` ran three queries
+  and threw the rows away; it now runs none. On a public endpoint an anonymous
+  caller no longer reaches the database with an unchecked `include`.
+- Answer 400, not 404, when a request carries both a bad `include` and a
+  missing id. The server must understand a request before it can report the
+  record absent, and JSON:API requires 400 for an include path it cannot
+  resolve. A 404 here tells the caller the record is missing when the server
+  never asked.
+
+### Fixed
+
+- Read a declared write list through the whole ancestor chain. Only the
+  direct subclass of a declaring resource inherited its
+  `creatable_fields`/`updatable_fields`; a grandchild fell open to the
+  attribute fallback and wrote any relationship. Any ancestor's declaration
+  now counts, and resolution still reads through the superclass, so an
+  intermediate reader override keeps its say at every level.
+- Read `attributes` and `relationships` from the resource object, not from a
+  `data` member nested inside it. The deserializer took the nested pair first,
+  and the controllers hand it the resource object, which the client writes. A
+  client nested a second `data` member and wrote fields that never appeared
+  where a host application's guard reads them. `type` now decides the shape:
+  JSON:API requires it in every resource object and names no `type` among the
+  members of a document. A hash that carries `type` is the resource object, and
+  the deserializer unwraps `data` only for a hash that carries no `type` over a
+  `data` member that carries one.
+
 ## [3.11.0]
 
 ### Changed

data/README.md

@@ -143,6 +143,42 @@ class UserResource < JSONAPI::Resource
 end
 ```
 
+A declared list is the complete allow-list. It names relationships as well as
+attributes, so the resource above lets a client write no relationship at all.
+Name a relationship in the list to let a client write it:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+  has_many :teams
+
+  creatable_fields :name, :email, :teams
+  updatable_fields :name, :teams
+end
+```
+
+Name a relationship in one list and not the other to make it create-only or
+update-only. A client that writes a relationship the action's list omits meets
+403 Forbidden. An omitted attribute is not an error: the deserializer drops it
+and the request answers 200.
+
+`creatable_fields` and `updatable_fields` are the only way to declare a list. A
+subclass that declares nothing reads its parent's lists and closes the same
+relationships.
+
+A resource that declares no list for an action keeps every relationship
+writable, because the fallback list is the attribute list, which names no
+relationship. Mark a relationship `readonly: true` to stop a write there.
+
+An override of `permitted_creatable_fields` or `permitted_updatable_fields` is
+not a declaration, and it leaves every relationship writable. An override that
+adjusts the inherited list — `super - [:role]` — returns a plain array, the same
+as one that states a fresh list, so jpie cannot tell the two apart. Call the DSL
+to close the list.
+
+The gate never runs for an ActiveStorage attachment, so a `has_one` backed by
+`has_one_attached` needs no entry in either list.
+
 ## Relationship Endpoints
 
 Manage relationship links independently of the parent resource. This will not delete the related resource itself, but only manage the relationship.
@@ -153,6 +189,15 @@ If the relationship is `User -(has_one)-> AccountUser -(belong_to)-> Account` an
 - `PATCH /users/:id/relationships/:relationship_name` - Replace relationship linkage
 - `DELETE /users/:id/relationships/:relationship_name` - Remove relationship linkage
 
+Each verb stands on a member action, so `only:` and `except:` govern it. `GET` stands on `:show`. `PATCH` and `DELETE` both stand on `:update`, because a relationship `DELETE` removes members from the relationship — the controller authorizes it as an update, and the primary record survives — so `:destroy` plays no part. A declaration that omits the member action grants no relationship path for its verbs:
+
+```ruby
+# Draws relationship GET alone: :update is omitted, so no PATCH and no DELETE.
+jsonapi_resources :posts, only: %i[index show create destroy]
+```
+
+The `:relationship` path helper hangs on the first verb drawn, so it survives a declaration that keeps a write verb and drops `:show`.
+
 ## Filtering
 
 Declare permitted filters in your resource class:
@@ -853,10 +898,6 @@ JSONAPI.configure do |config|
   # :same_namespace -> API::V1::VendorResource maps to API::V1::Vendor
   # :flat           -> API::V1::VendorResource maps to Vendor
   config.namespace_model_mapping = :same_namespace
-
-  # Fallback behavior when namespaced resource not found: true (default) or false
-  # When true, if API::V1::VendorResource not found, try VendorResource
-  config.namespace_fallback = true
 end
 ```
 
@@ -878,15 +919,35 @@ end
 This will:
 
 - Look for `API::V1::WidgetsController` (falls back to `JSONAPI::ResourcesController` if not found)
-- Load `API::V1::WidgetResource` (falls back to `WidgetResource` if `namespace_fallback: true`)
+- Load `API::V1::WidgetResource`
 - Pass `jsonapi_namespace: "api/v1"` to the controller
 
 The request namespace also selects the resource class during serialization: for
 the attributes, the include filter, the links, and the relationship linkage.
 `GET /portal/posts` serializes with `Portal::PostResource` even when the `Post`
-model is flat. When the namespaced resource does not exist, the loader falls
-back to the model's own namespace, then to the flat resource. Set
-`config.namespace_fallback = false` to refuse the flat fallback.
+model is flat.
+
+A namespace serves only what it declares. A namespaced request never resolves a
+flat resource: a route whose namespace carries no resource fails at draw time
+(the app does not boot), and an `?include=` hop the namespace cannot answer is
+a 400 at validation, before anything loads. For a namespaced model, both name
+shapes answer — `Pub::ItemResource` and `Pub::DepotItemResource` for
+`Depot::Item` — so the class a `MissingResourceClass` message names is always
+a working declaration. To serve a flat resource inside a
+namespace, declare it:
+
+```ruby
+class API::V1::WidgetResource < WidgetResource; end
+```
+
+That one line is the review trail: the namespace's public surface is exactly
+the set of resource classes defined in it. Two shapes need no declaration — a
+namespaced model still reaches the resource in its own namespace, and an STI
+record answers through the request namespace's resource for its own class,
+then for its base class, so one base resource covers every subclass.
+ActiveStorage attachments answer through the blob resource and are exempt.
+Polymorphic include hops cannot be judged at validation; each record's class
+resolves at serialization and raises if the namespace cannot answer it.
 
 #### Namespaced Resources
 

data/lib/json_api/configuration.rb

@@ -4,7 +4,7 @@ module JSONAPI
   class Configuration
     attr_accessor :default_page_size, :max_page_size, :jsonapi_meta, :authorization_handler,
                   :authorization_scope, :document_meta_resolver,
-                  :namespace_type_format, :namespace_model_mapping, :namespace_fallback,
+                  :namespace_type_format, :namespace_model_mapping,
                   :n1_detection_enabled,
                   :query_tracking_enabled, :query_count_threshold, :slow_query_threshold_ms,
                   :query_tracking_queries_cap,
@@ -87,7 +87,6 @@ module JSONAPI
     def set_namespace_defaults
       @namespace_type_format = :flat
       @namespace_model_mapping = :same_namespace
-      @namespace_fallback = true
     end
   end
 

data/lib/json_api/controllers/concerns/relationships/serialization.rb

@@ -37,7 +37,8 @@ module JSONAPI
         return fetch_blank_polymorphic(association) if type_value.blank? || id_value.blank?
 
         related_model_class = type_value.constantize
-        related_resource_class = JSONAPI::ResourceLoader.find_for_model(related_model_class)
+        related_resource_class = JSONAPI::ResourceLoader.find_for_model(related_model_class,
+                                                                        namespace: jsonapi_namespace,)
         base = apply_relationship_authorization(related_resource_class.records, related_model_class)
         record = base.find(id_value)
 
@@ -52,14 +53,14 @@ module JSONAPI
 
       def fetch_polymorphic_has_many_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
-        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
+        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass, namespace: jsonapi_namespace)
         base = apply_relationship_authorization(related_resource_class.records, association.klass)
         association_instance.scope.merge(base)
       end
 
       def fetch_non_polymorphic_related_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
-        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
+        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass, namespace: jsonapi_namespace)
         base = apply_relationship_authorization(related_resource_class.records, association.klass)
         scope = association_instance.scope.merge(base)
 

data/lib/json_api/controllers/concerns/relationships/sorting.rb

@@ -13,7 +13,7 @@ module JSONAPI
         sorts = parse_sort_param
         return related if sorts.empty?
 
-        resource_class = ResourceLoader.find_for_model(association.klass)
+        resource_class = ResourceLoader.find_for_model(association.klass, namespace: jsonapi_namespace)
         Support::Sort.new(sort_params: sorts, resource_class:).apply(related)
       end
     end

data/lib/json_api/controllers/concerns/resource_actions/include_validation.rb

@@ -30,13 +30,38 @@ module JSONAPI
 
           assoc = current.reflect_on_association(name.to_sym)
           return false unless assoc
+          # A polymorphic hop has no single target class, so no static check can
+          # judge it here; each record's class resolves at serialization.
           break if assoc.polymorphic?
 
           current = assoc.klass
+          return false unless include_hop_resolvable?(current)
         end
         true
       end
 
+      # A namespaced request serves an include only where the namespace carries a
+      # resource to answer it. A hop that resolves nothing is a 400 here, not a
+      # MissingResourceClass halfway through serialization.
+      def include_hop_resolvable?(klass)
+        JSONAPI::ResourceLoader.find_for_model(klass, namespace: jsonapi_namespace)
+        true
+      rescue JSONAPI::ResourceLoader::MissingResourceClass
+        false
+      end
+
+      # Validation cannot judge a polymorphic hop, so the namespace's answer
+      # only arrives when a record's class resolves at serialization. Render
+      # the refusal validation would have given, never a raw 500.
+      def render_unanswerable_include(error)
+        render_parameter_errors(
+          [error.message],
+          title: "Invalid Include Path",
+          detail_proc: ->(m) { m },
+          source_proc: ->(_) { { parameter: "include" } },
+        )
+      end
+
       def render_include_errors(invalid)
         render_parameter_errors(
           invalid,

data/lib/json_api/controllers/concerns/resource_actions/resource_loading.rb

@@ -7,13 +7,21 @@ module JSONAPI
 
       private
 
-      def load_jsonapi_resource
+      # jsonapi_resources resolves the resource at draw time, so a typed route with no
+      # resource class is a hand-drawn misconfiguration. Answer it 404, the way the
+      # relationships controller's set_resource_class does — a nil class here surfaced
+      # later as a NoMethodError 500 in whichever action read it first.
+      def load_jsonapi_resource_class
         @resource_name = params[:resource_type]&.singularize
         @jsonapi_namespace = params[:jsonapi_namespace].presence
         load_resource_and_model_class
-        load_resource_record
-      rescue JSONAPI::ResourceLoader::MissingResourceClass
+      rescue JSONAPI::ResourceLoader::MissingResourceClass => e
         @resource_class = nil
+        render_resource_not_found_error(e.message)
+      end
+
+      def load_jsonapi_resource
+        load_resource_record
       rescue ActiveRecord::RecordNotFound
         render_record_not_found
       end

data/lib/json_api/controllers/concerns/resource_actions.rb

@@ -24,10 +24,14 @@ module JSONAPI
     include ResourceLoading
 
     included do
-      before_action :load_jsonapi_resource
+      before_action :load_jsonapi_resource_class
+      # A query parameter shapes the query the loader builds, so judge every one of them
+      # before the loader reads the database. The body members stay after the load,
+      # because a conflict with the addressed record needs that record.
       before_action :validate_fields_param, only: %i[index show]
       before_action :validate_filter_param, only: [:index]
       before_action :validate_include_param, only: %i[index show]
+      before_action :load_jsonapi_resource
       before_action :validate_resource_type!, only: %i[create update]
       before_action :validate_resource_id!, only: [:update]
     end
@@ -39,11 +43,15 @@ module JSONAPI
       @total_count = query.total_count
       @pagination_applied = query.pagination_applied
       render json: serialize_collection(query.scope), status: :ok
+    rescue JSONAPI::ResourceLoader::MissingResourceClass => e
+      render_unanswerable_include(e)
     end
 
     def show
       authorize_resource_action!(@resource, action: :show)
       render json: serialize_resource(@resource), status: :ok
+    rescue JSONAPI::ResourceLoader::MissingResourceClass => e
+      render_unanswerable_include(e)
     end
 
     def create

data/lib/json_api/controllers/relationships_controller.rb

@@ -20,6 +20,13 @@ module JSONAPI
     skip_before_action :validate_resource_type!, only: %i[update destroy]
     skip_before_action :validate_resource_id!, only: %i[update destroy]
 
+    # A polymorphic or namespaced relationship can only learn at serialization
+    # that the request namespace carries no resource for the record's class.
+    # Answer 404, the same as set_resource_class does for the primary type.
+    rescue_from JSONAPI::ResourceLoader::MissingResourceClass do |error|
+      render_resource_not_found_error(error.message)
+    end
+
     before_action :set_resource_name
     before_action :set_resource_class
     before_action :set_resource

data/lib/json_api/resources/concerns/attributes_dsl.rb

@@ -42,18 +42,44 @@ module JSONAPI
         end
 
         # Whether a relationship may be written for the given action (:create or :update).
-        # A relationship is gated by the creatable_fields/updatable_fields allow-list only when
-        # the resource opted it in by naming it in one of those lists; relationships named in
-        # neither keep the default (readonly-only) behavior. This lets a resource make a
-        # relationship create-only — name it in creatable_fields, omit it from updatable_fields —
-        # the same way it restricts attributes.
+        # A declared list is the complete allow-list. A resource that declares the action's
+        # field list names every field a client may write, and the deserializer refuses a
+        # relationship the list omits. Naming a relationship in one list and not the other
+        # still makes it create-only or update-only, the same way it restricts attributes.
+        #
+        # A resource that declares no list for the action keeps the older behavior, and only
+        # `readonly: true` stops the write. The fallback list is the attribute list, which
+        # names no relationship, so failing closed there would refuse every resource that
+        # never stated an opinion.
         def relationship_field_writable?(name, action)
           name = name.to_sym
           creatable = permitted_creatable_fields.map(&:to_sym)
           updatable = permitted_updatable_fields.map(&:to_sym)
-          return true unless creatable.include?(name) || updatable.include?(name)
+          if creatable.include?(name) || updatable.include?(name)
+            return (action == :create ? creatable : updatable).include?(name)
+          end
 
-          (action == :create ? creatable : updatable).include?(name)
+          !field_list_declared?(action)
+        end
+
+        # Whether the resource declares the action's field list, rather than falling back to
+        # the attribute list. The DSL records a declaration in the instance variable, and a
+        # subclass reads its parent's. Those are the two signals `resolve_field_list` treats
+        # as declared, and this asks the same question of the same two.
+        #
+        # An override of the reader is not a signal. An override that adjusts the inherited
+        # list — `super - [:draft] + [:owners]` — returns a plain array, the same as one that
+        # states a fresh list, so the two cannot be told apart. Reading an override as a
+        # declaration would refuse every relationship an adjusting resource does not name,
+        # and such a resource names attributes only. Call the DSL to close the list.
+        def field_list_declared?(action)
+          ivar, method = if action == :create
+                           %i[@creatable_fields permitted_creatable_fields]
+                         else
+                           %i[@updatable_fields permitted_updatable_fields]
+                         end
+
+          instance_variable_defined?(ivar) || inherits_field?(ivar, method)
         end
 
         def resolve_field_list(ivar, method)
@@ -63,10 +89,18 @@ module JSONAPI
           permitted_attributes.uniq
         end
 
+        # Any ancestor's declaration counts. Reading the immediate parent alone let a
+        # grandchild of a declaring resource fall open to the attribute fallback. The
+        # resolution still reads through `superclass.public_send`, so an intermediate
+        # reader override — the adjuster shape — keeps its say at every level.
         def inherits_field?(ivar, method)
-          superclass != JSONAPI::Resource &&
-            superclass.respond_to?(method) &&
-            superclass.instance_variable_defined?(ivar)
+          klass = superclass
+          while klass != JSONAPI::Resource && klass.respond_to?(method)
+            return true if klass.instance_variable_defined?(ivar)
+
+            klass = klass.superclass
+          end
+          false
         end
 
         def should_inherit_attributes?(declared_attributes)

data/lib/json_api/resources/resource_loader.rb

@@ -39,7 +39,7 @@ module JSONAPI
     end
 
     def self.find(resource_type, namespace: nil)
-      key = "#{namespace}|#{resource_type}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+      key = "#{namespace}|#{resource_type}"
       cached = @find_cache[key]
       return cached if cached
 
@@ -48,19 +48,12 @@ module JSONAPI
       @find_cache[key] = klass
     end
 
+    # A namespaced request resolves inside its namespace alone — "widgets" under
+    # "api/v1" names API::V1::WidgetResource and nothing else. A flat request
+    # names the flat resource. Nothing falls back across the boundary, so a
+    # namespace serves only what it declares.
     def self.find_candidates(resource_type, namespace)
-      candidates = []
-
-      # Namespaced resource, e.g. "widgets" with namespace "api/v1" → API::V1::WidgetResource
-      candidates << build_resource_class_name(resource_type, namespace) if namespace
-
-      # Flat resource, e.g. "widgets" → WidgetResource
-      if !namespace || JSONAPI.configuration.namespace_fallback
-        candidates << build_resource_class_name(resource_type,
-                                                nil,)
-      end
-
-      candidates
+      [build_resource_class_name(resource_type, namespace.presence)]
     end
 
     def self.find_for_model(model_class, namespace: nil)
@@ -71,10 +64,7 @@ module JSONAPI
     end
 
     def self.model_identity_bucket(namespace)
-      fallback = @model_identity_cache.compute_if_absent(JSONAPI.configuration.namespace_fallback ? 1 : 0) do
-        Concurrent::Map.new
-      end
-      fallback.compute_if_absent(namespace) { Concurrent::Map.new }
+      @model_identity_cache.compute_if_absent(namespace) { Concurrent::Map.new }
     end
 
     def self.find_for_model_uncached(model_class, namespace)
@@ -99,19 +89,39 @@ module JSONAPI
     def self.model_cache_key(model_class, namespace)
       return "::#{model_class.name}" unless namespace
 
-      "#{namespace}|::#{model_class.name}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+      "#{namespace}|::#{model_class.name}"
     end
 
-    # The request namespace outranks the model's own namespace, which stays a
-    # fallback so a namespaced model still reaches its own resource. The flat
-    # name comes last, and only while the configuration allows the fallback.
+    # The request namespace outranks the model's own namespace, which a
+    # namespaced model keeps so it still reaches its own resource. An STI
+    # record answers through the request namespace's resource for its own
+    # class, then for its base class, so one base resource covers every
+    # subclass. No flat name is a candidate: a flat resource is another
+    # namespace's surface, and resolving it here is what published internal
+    # fields on public portals.
     def self.request_namespace_candidates(model_class, namespace, model_namespace)
-      resource_type = model_class.name.demodulize.underscore.pluralize
-      candidates = [build_resource_class_name(resource_type, namespace)]
+      candidates = sti_resource_names(model_class, namespace)
       candidates |= model_candidates(model_class, model_namespace)
-      return candidates if JSONAPI.configuration.namespace_fallback
+      candidates - sti_resource_names(model_class, nil)
+    end
+
+    # Every name shape a class answers to, in one namespace: the demodulized
+    # name and, for a namespaced model, the flat-combined name `find` builds
+    # from the route type — so `Pub::DepotItemResource`, the class the
+    # MissingResourceClass message names, is a candidate, and the flat
+    # `DepotItemResource` is subtracted with the rest.
+    def self.sti_resource_names(model_class, namespace)
+      classes = [model_class]
+      classes << model_class.base_class if sti_subclass?(model_class)
+      classes.flat_map { class_resource_names(it, namespace) }
+    end
+
+    def self.class_resource_names(klass, namespace)
+      names = [build_resource_class_name(klass.name.demodulize.underscore.pluralize, namespace)]
+      return names unless klass.name.include?("::")
 
-      candidates - [build_resource_class_name(resource_type, nil)]
+      combined = "#{klass.name.gsub("::", "")}Resource"
+      names << (namespace ? "#{namespace.to_s.camelize}::#{combined}" : combined)
     end
 
     def self.build_resource_class_name(resource_type, namespace)

data/lib/json_api/routing.rb

@@ -2,17 +2,29 @@
 
 module JSONAPI
   module Routing
+    # The member action each relationship route stands on. A relationship
+    # route reads or writes through the parent record: GET stands on :show,
+    # and PATCH and DELETE both stand on :update, because a relationship
+    # DELETE removes members from the relationship — the controller
+    # authorizes it as an update, and the primary record survives — so
+    # :destroy plays no part.
+    RELATIONSHIP_ACTIONS = { show: :show, update: :update, destroy: :update }.freeze
+
     def jsonapi_resources(resource, controller: nil, defaults: {}, sti: false, **options, &)
       resource_name = resource.to_s
       namespace = extract_namespace_from_scope
       controller ||= detect_controller(resource_name, namespace)
       defaults = build_jsonapi_defaults(defaults, resource_name, namespace)
+      # The caller's restriction, before the STI base overwrite: a subtype route
+      # that states no options of its own inherits it, so `only:` governs the
+      # whole set rather than the base alone.
+      restriction = options.slice(:only, :except)
       options[:only] = :index if sti
       options = without_form_actions(options)
 
       JSONAPI::ResourceLoader.find(resource_name, namespace:)
       define_resource_routes(resource, controller, defaults, options, &)
-      define_sti_routes(resource, resource_name, defaults, sti, namespace)
+      define_sti_routes(resource, defaults, sti, namespace, restriction)
     end
 
     def build_jsonapi_defaults(defaults, resource_name, namespace)
@@ -50,17 +62,35 @@ module JSONAPI
     end
 
     def define_resource_routes(resource, controller, defaults, options, &block)
+      actions = permitted_relationship_actions(options)
       resources(resource, controller:, defaults:, **options) do
-        define_relationship_routes
+        define_relationship_routes(actions)
         instance_eval(&block) if block
       end
     end
 
-    def define_relationship_routes
+    # The relationships controller authorizes the parent record, never the
+    # member action the caller left out. So a caller who omitted `:update` still
+    # got the relationship PATCH, a write path they never asked for.
+    def permitted_relationship_actions(options)
+      named = options.key?(:only) ? Array(options[:only]).map(&:to_sym) : RELATIONSHIP_ACTIONS.values
+      kept = named - Array(options[:except]).map(&:to_sym)
+      RELATIONSHIP_ACTIONS.select { |_action, member| kept.include?(member) }.keys
+    end
+
+    # The :relationship helper hangs on the first verb drawn, so it survives
+    # a declaration that keeps a write verb and drops :show.
+    def define_relationship_routes(actions)
+      return if actions.empty?
+
       member do
-        get "relationships/:relationship_name", to: relationships_endpoint(:show), as: :relationship
-        patch "relationships/:relationship_name", to: relationships_endpoint(:update)
-        delete "relationships/:relationship_name", to: relationships_endpoint(:destroy)
+        path = "relationships/:relationship_name"
+        { get: :show, patch: :update, delete: :destroy }.each do |verb, action|
+          next unless actions.include?(action)
+
+          name = (:relationship if action == actions.first)
+          public_send(verb, path, to: relationships_endpoint(action), as: name)
+        end
       end
     end
 
@@ -77,29 +107,31 @@ module JSONAPI
       end
     end
 
-    def define_sti_routes(resource, resource_name, defaults, sti, namespace = nil)
+    def define_sti_routes(resource, defaults, sti, namespace, restriction)
       return unless sti
 
       if sti.is_a?(Array)
-        define_explicit_sti_routes(sti, defaults)
+        define_explicit_sti_routes(sti, defaults, restriction)
       else
-        define_auto_sti_routes(resource, resource_name, defaults, namespace)
+        define_auto_sti_routes(resource, defaults, namespace, restriction)
       end
     end
 
-    def define_explicit_sti_routes(sti_resources, defaults)
+    # A subtype entry that states its own options is a declaration and keeps it.
+    # A bare entry declares nothing, so it inherits the caller's restriction.
+    def define_explicit_sti_routes(sti_resources, defaults, restriction)
       sti_resources.each do |entry|
         case entry
         in Hash
           entry.each { |sub_resource_name, options| jsonapi_resources(sub_resource_name, defaults:, **options) }
         else
-          jsonapi_resources(entry, defaults:)
+          jsonapi_resources(entry, defaults:, **restriction)
         end
       end
     end
 
-    def define_auto_sti_routes(resource, resource_name, defaults, namespace = nil)
-      resource_class = JSONAPI::ResourceLoader.find(resource_name, namespace:)
+    def define_auto_sti_routes(resource, defaults, namespace, restriction)
+      resource_class = JSONAPI::ResourceLoader.find(resource.to_s, namespace:)
       model_class = resource_class.model_class
       return unless model_class.respond_to?(:descendants)
 
@@ -107,7 +139,7 @@ module JSONAPI
         sub_resource_name = subclass.name.demodulize.underscore.pluralize.to_sym
         next if sub_resource_name == resource.to_sym
 
-        jsonapi_resources(sub_resource_name, defaults:)
+        jsonapi_resources(sub_resource_name, defaults:, **restriction)
       rescue NameError, JSONAPI::ResourceLoader::MissingResourceClass
         next
       end

data/lib/json_api/serialization/concerns/attributes_deserialization.rb

@@ -10,7 +10,7 @@ module JSONAPI
       end
 
       def extract_attributes_from_params
-        @params.dig(:data, :attributes) || @params[:attributes] || {}
+        @params[:attributes] || {}
       end
 
       def permitted_attributes_for_action

data/lib/json_api/serialization/concerns/relationships_deserialization.rb

@@ -4,7 +4,7 @@ module JSONAPI
   module Serialization
     module RelationshipsDeserialization
       def relationships
-        rels = @params.dig(:data, :relationships) || @params[:relationships] || {}
+        rels = @params[:relationships] || {}
         rels = rels.to_h if rels.respond_to?(:to_h)
         rels.is_a?(Hash) ? rels : {}
       end

data/lib/json_api/serialization/deserializer.rb

@@ -17,7 +17,7 @@ module JSONAPI
     include Serialization::DeserializationHelpers
 
     def initialize(params, model_class:, action: :create, definition: nil)
-      @params = ParamHelpers.deep_symbolize_params(params)
+      @params = resource_object(ParamHelpers.deep_symbolize_params(params))
       @model_class = model_class
       # Prefer the resource the request is addressing (resolved by type/route). Resolving
       # from the model alone is ambiguous when several resources share one model
@@ -26,5 +26,21 @@ module JSONAPI
       @definition = definition || ResourceLoader.find_for_model(model_class)
       @action = action.to_sym
     end
+
+    private
+
+    # A caller passes either the whole document or the resource object inside it, and the
+    # controllers pass the resource object, which the client writes. `type` settles which one
+    # arrived: JSON:API requires it in every resource object and names no `type` among the
+    # members of a document. So a hash that carries `type` is the resource object, and only a
+    # hash that carries none, over a `data` member that carries one, is a document. Anything
+    # else is neither, and the outer hash wins. A reader that took a nested `data` first let a
+    # client hide an attribute or a relationship from a guard that reads the request body.
+    def resource_object(params)
+      return params if params.key?(:type)
+      return params unless params[:data].is_a?(Hash) && params[:data].key?(:type)
+
+      params[:data]
+    end
   end
 end

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "3.11.0"
+  VERSION = "4.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 3.11.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Emil Kampp