jpie 1.0.0 → 1.0.1

data/README.md

@@ -17,34 +17,18 @@ A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'json_api'
+```bash
+bundle add jpie
 ```
 
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install json_api
-
 ## Requirements
 
 - Ruby >= 3.4.0
 - Rails >= 8.0.0
 
-## Usage
-
-### Basic Setup
-
-Add the gem to your Gemfile and run `bundle install`. The gem will automatically register the JSON:API MIME type and extend Rails routing.
-
-### Routing
+## Routing
 
-Use the `jsonapi_resources` DSL in your routes file:
+Use the `jsonapi_resources` DSL in your routes file to create standard RESTful routes (index, show, create, update, destroy) that default to the `json_api/resources` controller and `jsonapi` format:
 
 ```ruby
 # config/routes.rb
@@ -54,11 +38,13 @@ Rails.application.routes.draw do
 end
 ```
 
-This creates standard RESTful routes (index, show, create, update, destroy) that default to the `json_api/resources` controller and `jsonapi` format.
+To use a custom controller instead of the default:
 
-**Important**: Each resource must have a corresponding resource class defined (e.g., `UserResource` for `jsonapi_resources :users`). The routing will fail at boot time if the resource class is missing.
+```ruby
+jsonapi_resources :users, controller: "api/users"
+```
 
-### Resource Definitions
+## Resource Definitions
 
 Define resource classes to control which attributes and relationships are exposed via the JSON:API endpoint:
 
@@ -72,27 +58,8 @@ class UserResource < JSONAPI::Resource
 end
 ```
 
-Resource classes must:
-
-- Inherit from `JSONAPI::Resource`
-- Be named `<ResourceName>Resource` (e.g., `UserResource` for `users` resource type)
-- Define permitted attributes using `attributes`
-- Define relationships using `has_many`, `has_one`, or `belongs_to`
-
-The generic controller uses these resource definitions to:
-
-- Validate requested fields (sparse fieldsets)
-- Validate requested includes
-- Control which attributes are exposed in responses
-- Validate filters
-- Control which fields can be created vs updated
-
 ### Virtual Attributes
 
-Resources can define virtual attributes that don't correspond to database columns. Virtual attributes are useful for computed values, formatted data, or transforming model attributes.
-
-#### Defining Virtual Attributes
-
 To create a virtual attribute, declare it in `attributes` and implement a getter method:
 
 ```ruby
@@ -122,24 +89,7 @@ The getter method receives the underlying model instance via `resource`. Virtual
 }
 ```
 
-#### Overriding Model Attributes
-
-Resource getters take precedence over model attributes. If you define a getter for a real database column, it will override the model's attribute value:
-
-```ruby
-class UserResource < JSONAPI::Resource
-  attributes :name, :email
-
-  # Override name attribute
-  def name
-    resource.name.upcase
-  end
-end
-```
-
-#### Virtual Attribute Setters
-
-You can define setters for virtual attributes that transform incoming values into real model attributes. This is useful for accepting formatted input that needs to be stored differently:
+You can also define setters for virtual attributes that transform incoming values into real model attributes:
 
 ```ruby
 class UserResource < JSONAPI::Resource
@@ -173,208 +123,32 @@ When a client sends `display_name` in a create or update request, the setter tra
 
 **Important**: You must initialize `@transformed_params` in your `initialize` method if you use setters that modify it.
 
-### Custom Controllers
+### Creatable and Updatable Fields
 
-If you need custom behavior, you can override the default controller:
+By default, all attributes are available for both create and update. Restrict fields per operation:
 
 ```ruby
-jsonapi_resources :users, controller: "api/users"
-```
-
-### Controller Actions
-
-The default `JSONAPI::ResourcesController` provides:
-
-- `GET /users` - List all users (with filtering, sorting, pagination)
-- `GET /users/:id` - Show a user (with includes, sparse fieldsets)
-- `POST /users` - Create a user (with relationships)
-- `PATCH /users/:id` - Update a user (with relationships)
-- `DELETE /users/:id` - Delete a user
-
-Additionally, relationship endpoints are available via `JSONAPI::RelationshipsController`:
-
-- `GET /users/:id/relationships/:relationship_name` - Show relationship data (with sorting for collections)
-- `PATCH /users/:id/relationships/:relationship_name` - Update relationship linkage
-- `DELETE /users/:id/relationships/:relationship_name` - Remove relationship linkage
-
-#### Example Responses
-
-**GET /users (Collection Response):**
-
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "data": [
-    {
-      "type": "users",
-      "id": "1",
-      "attributes": {
-        "name": "John Doe",
-        "email": "john@example.com",
-        "phone": "555-0100"
-      },
-      "relationships": {
-        "posts": {
-          "data": [
-            { "type": "posts", "id": "1" },
-            { "type": "posts", "id": "2" }
-          ],
-          "meta": {
-            "count": 2
-          }
-        },
-        "profile": {
-          "data": null
-        }
-      },
-      "links": {
-        "self": "/users/1"
-      },
-      "meta": {
-        "created_at": "2024-01-15T10:30:00Z",
-        "updated_at": "2024-01-15T10:30:00Z"
-      }
-    }
-  ]
-}
-```
-
-**GET /users/:id (Single Resource Response):**
-
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "data": {
-    "type": "users",
-    "id": "1",
-    "attributes": {
-      "name": "John Doe",
-      "email": "john@example.com",
-      "phone": "555-0100"
-    },
-    "relationships": {
-      "posts": {
-        "data": [
-          { "type": "posts", "id": "1" },
-          { "type": "posts", "id": "2" }
-        ],
-        "meta": {
-          "count": 2
-        }
-      },
-      "profile": {
-        "data": {
-          "type": "admin_profiles",
-          "id": "1"
-        }
-      }
-    },
-    "links": {
-      "self": "/users/1"
-    },
-    "meta": {
-      "created_at": "2024-01-15T10:30:00Z",
-      "updated_at": "2024-01-15T10:30:00Z"
-    }
-  }
-}
-```
-
-**POST /users (Create Response):**
-
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "data": {
-    "type": "users",
-    "id": "2",
-    "attributes": {
-      "name": "New User",
-      "email": "newuser@example.com",
-      "phone": "555-0101"
-    },
-    "relationships": {
-      "posts": {
-        "data": [],
-        "meta": {
-          "count": 0
-        }
-      },
-      "profile": {
-        "data": null
-      }
-    },
-    "links": {
-      "self": "/users/2"
-    },
-    "meta": {
-      "created_at": "2024-01-15T11:00:00Z",
-      "updated_at": "2024-01-15T11:00:00Z"
-    }
-  }
-}
-```
-
-**PATCH /users/:id (Update Response):**
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :phone, :role
 
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "data": {
-    "type": "users",
-    "id": "1",
-    "attributes": {
-      "name": "Updated Name",
-      "email": "john@example.com",
-      "phone": "555-9999"
-    },
-    "relationships": {
-      "posts": {
-        "data": [{ "type": "posts", "id": "1" }],
-        "meta": {
-          "count": 1
-        }
-      },
-      "profile": {
-        "data": null
-      }
-    },
-    "links": {
-      "self": "/users/1"
-    },
-    "meta": {
-      "created_at": "2024-01-15T10:30:00Z",
-      "updated_at": "2024-01-15T11:15:00Z"
-    }
-  }
-}
+  creatable_fields :name, :email, :phone  # role is system-set
+  updatable_fields :name, :phone          # email is immutable
+end
 ```
 
-**DELETE /users/:id:**
+## Relationship Endpoints
 
-Returns `204 No Content` with an empty response body.
+Manage relationship links independently of the parent resource. This will not delete the related resource itself, but only manage the relationship.
 
-### Query Parameters
+If the relationship is `User -(has_one)-> AccountUser -(belong_to)-> Account` and we DELETE `/users/1/relationships/account` this will not delete the account, but delete the account user.
 
-The controller supports standard JSON:API query parameters:
-
-- `filter[name]=John` - Filter resources (must be declared in resource class)
-- `sort=name,-created_at` - Sort resources (ascending by default, prefix with `-` for descending)
-- `page[number]=1&page[size]=25` - Pagination (number and size only)
-- `include=posts,comments` - Include related resources
-- `fields[users]=name,email` - Sparse fieldsets
+- `GET /users/:id/relationships/:relationship_name` - Show relationship linkage
+- `PATCH /users/:id/relationships/:relationship_name` - Replace relationship linkage
+- `DELETE /users/:id/relationships/:relationship_name` - Remove relationship linkage
 
-#### Filtering
+## Filtering
 
-Filtering requires declaring permitted filters in your resource class:
+Declare permitted filters in your resource class:
 
 ```ruby
 class UserResource < JSONAPI::Resource
@@ -383,399 +157,253 @@ class UserResource < JSONAPI::Resource
 end
 ```
 
-For regular filters, the gem applies column-aware operators when you use suffixes:
-
-- `_eq`
-- `_match` (string/text; uses ILIKE with sanitized patterns)
-- `_lt`, `_lte`, `_gt`, `_gte` (numeric, date, datetime)
-
-If a filter name doesn't match a supported operator but a model scope with that name exists, the scope is called instead. Filters are only applied when declared via `filters`. Invalid filter names return a `400 Bad Request` error.
-
-#### Filter Value Formats
-
-Filter values can be provided as either strings or arrays, depending on the filter's requirements:
+Filters ending in `_eq`, `_match`, `_lt`, `_lte`, `_gt`, or `_gte` are applied to the corresponding column:
 
-**String Format:**
-
-- Single value: `filter[name_eq]=John`
-- Comma-separated values: `filter[name_eq]=John,Jane` (parsed as a single string `"John,Jane"`)
-
-**Array Format:**
-
-- Multiple values: `filter[categories_include][]=security&filter[categories_include][]=governance`
-- Rails parses this as an array: `["security", "governance"]`
-
-**When Arrays Are Required:**
-
-Some filters require arrays, particularly when using PostgreSQL array operators:
-
-```ruby
-class SelectedControl < ApplicationRecord
-  # This scope uses PostgreSQL's ?| operator which requires an array
-  scope :categories_include, ->(categories) {
-    where("#{table_name}.categories ?| array[:categories]", categories:)
-  }
-end
 ```
-
-For such scopes, filters must be provided in array format:
-
-- ✅ Correct: `filter[categories_include][]=security&filter[categories_include][]=governance`
-- ❌ Incorrect: `filter[categories_include]=security,governance` (parsed as string `"security,governance"`)
-
-**How Rails Parses Query Parameters:**
-
-- `filter[key]=value` → Rails parses as `{ "filter" => { "key" => "value" } }`
-- `filter[key][]=value1&filter[key][]=value2` → Rails parses as `{ "filter" => { "key" => ["value1", "value2"] } }`
-- `filter[key]=value1,value2` → Rails parses as `{ "filter" => { "key" => "value1,value2" } }` (single string)
-
-The `json_api` gem passes filter values directly to model scopes as parsed by Rails. If a scope expects an array (e.g., for PostgreSQL array operators), ensure the filter is sent in array format.
-
-#### Filtering through relationships (nested filter hashes)
-
-Expose filters on related resources using nested hashes. Relationships declared with `has_one`/`has_many` automatically allow nested filters on the related resource's filters plus primary key filters. Example:
-
-```ruby
-class PostResource < JSONAPI::Resource
-  filters :title
-end
-
-class User < ApplicationRecord
-  # Column filters: filter[user][email]=foo@example.com
-  # Scope filters: filter[user][name_search]=Jane
-  scope :name_search, ->(query) { where("users.name LIKE ?", "%#{query}%") }
-end
+GET /users?filter[name_eq]=John
+GET /users?filter[created_at_gte]=2024-01-01
 ```
 
-Examples:
-
-- `GET /posts?filter[user][id]=123` (joins users and filters on users.id)
-- `GET /posts?filter[user][email]=jane@example.com` (filters on related column)
-- `GET /posts?filter[user][name_search]=Jane` (calls the related scope and merges it)
-- `GET /comments?filter[post][user][email_eq]=john@example.com` (multi-level chain)
+Filter through relationships by nesting the filter key:
 
-Nested filter paths must point to either a column on the related model, a class method/scope on that model, or a filter declared on the related resource.
-
-Invalid filter fields will return a `400 Bad Request` error:
-
-```json
-{
-  "errors": [
-    {
-      "status": "400",
-      "title": "Invalid Filter",
-      "detail": "Invalid filters requested: invalid_field"
-    }
-  ]
-}
 ```
-
-### Writable through relationships
-
-By default, has-many-through and has-one-through relationships are writable via JSON:API payloads and relationship endpoints. Set `readonly: true` on the relationship to block writes and return `ParameterNotAllowed`.
-
-```ruby
-class UserResource < JSONAPI::Resource
-  has_many :post_comments, readonly: true
-end
+GET /posts?filter[user][email]=jane@example.com
+GET /comments?filter[post][user][id]=123
 ```
 
-- The opt-out applies to both main resource deserialization and relationship controller updates.
-- Use `readonly: true` when the underlying model should not allow assignment (for example, when it lacks `*_ids` setters or manages joins differently).
-- Without the flag, through relationships are writable.
+To pass multiple values, use bracket notation:
 
-#### Pagination
-
-Resources can be paginated using the `page[number]` and `page[size]` parameters. Pagination is only available on collection (index) endpoints.
+```
+GET /users?filter[roles][]=admin&filter[roles][]=editor
+```
 
-Examples:
+## Pagination
 
-- `GET /users?page[number]=1&page[size]=10` (first page, 10 items per page)
-- `GET /users?page[number]=2&page[size]=10` (second page, 10 items per page)
-- `GET /users?page[number]=1` (first page with default page size)
+Paginate collections with `page[number]` and `page[size]`:
 
-The default page size is 25, and the maximum page size is 100 (configurable via `JSONAPI.configuration`). If a size larger than the maximum is requested, it will be capped at the maximum.
+```
+GET /users?page[number]=1&page[size]=10
+GET /users?page[number]=2&page[size]=25
+```
 
-**Example Paginated Response:**
+Paginated responses include a `links` object with `self`, `first`, `last`, and conditional `prev`/`next` URLs, plus `meta.total` with the full count:
 
 ```json
 {
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "data": [
-    {
-      "type": "users",
-      "id": "1",
-      "attributes": {
-        "name": "User 1",
-        "email": "user1@example.com",
-        "phone": "555-0001"
-      },
-      "links": {
-        "self": "/users/1"
-      }
-    }
-  ],
+  "data": [...],
   "links": {
-    "self": "/users?page[number]=2&page[size]=5",
-    "first": "/users?page[number]=1&page[size]=5",
-    "last": "/users?page[number]=3&page[size]=5",
-    "prev": "/users?page[number]=1&page[size]=5",
-    "next": "/users?page[number]=3&page[size]=5"
+    "self": "/users?page[number]=2&page[size]=10",
+    "first": "/users?page[number]=1&page[size]=10",
+    "last": "/users?page[number]=5&page[size]=10",
+    "prev": "/users?page[number]=1&page[size]=10",
+    "next": "/users?page[number]=3&page[size]=10"
   },
-  "meta": {
-    "total": 15
-  }
+  "meta": { "total": 42 }
 }
 ```
 
-#### Including Related Resources
+Default page size is 25, maximum is 100 (configurable).
 
-Use the `include` parameter to include related resources in the response. This is available on both index and show endpoints:
+## Includes
 
-```ruby
-# Include single relationship
-GET /users?include=posts
+Include related resources with the `include` parameter:
 
-# Include multiple relationships
+```
+GET /users?include=posts
 GET /users?include=posts,comments
-
-# Include nested relationships (two levels)
-GET /users?include=posts.comments
-
-# Include deeply nested relationships (arbitrary depth)
 GET /users?include=posts.comments.author
-
-# Include multiple nested paths
-GET /users?include=posts.comments,posts.author
-
-# Mix single and nested includes
-GET /users?include=posts.comments,notifications
 ```
 
-The gem supports arbitrary depth for nested includes. You can chain as many associations as needed (e.g., `posts.comments.author.profile`). Overlapping paths are automatically merged, so `posts.comments` and `posts.comments.author` will correctly include posts, comments, and authors.
-
-Invalid include paths will return a `400 Bad Request` error with a JSON:API error response:
+Nested includes use dot notation and support arbitrary depth. Related resources appear in the `included` array, and relationships reference them by `type` and `id`:
 
 ```json
 {
-  "errors": [
-    {
-      "status": "400",
-      "title": "Invalid Include Path",
-      "detail": "Invalid include paths requested: invalid_association"
-    }
-  ]
-}
-```
-
-Included resources appear in the `included` array at the top level of the response, and relationships reference them using resource identifiers (`type` and `id`).
-
-**Example Response with Includes:**
-
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
   "data": {
     "type": "users",
     "id": "1",
-    "attributes": {
-      "name": "John Doe",
-      "email": "john@example.com",
-      "phone": "555-0100"
-    },
     "relationships": {
       "posts": {
-        "data": [
-          { "type": "posts", "id": "1" },
-          { "type": "posts", "id": "2" }
-        ],
-        "meta": {
-          "count": 2
-        }
+        "data": [{ "type": "posts", "id": "5" }]
       }
-    },
-    "links": {
-      "self": "/users/1"
     }
   },
   "included": [
     {
       "type": "posts",
-      "id": "1",
-      "attributes": {
-        "title": "First Post",
-        "body": "Content 1"
-      },
-      "relationships": {
-        "user": {
-          "data": {
-            "type": "users",
-            "id": "1"
-          }
-        },
-        "comments": {
-          "data": [],
-          "meta": {
-            "count": 0
-          }
-        }
-      },
-      "links": {
-        "self": "/posts/1"
-      }
-    },
-    {
-      "type": "posts",
-      "id": "2",
-      "attributes": {
-        "title": "Second Post",
-        "body": "Content 2"
-      },
-      "relationships": {
-        "user": {
-          "data": {
-            "type": "users",
-            "id": "1"
-          }
-        },
-        "comments": {
-          "data": [],
-          "meta": {
-            "count": 0
-          }
-        }
-      },
-      "links": {
-        "self": "/posts/2"
-      }
+      "id": "5",
+      "attributes": { "title": "Hello World" }
     }
   ]
 }
 ```
 
-#### Polymorphic Relationships
+## Polymorphic Relationships
+
+Polymorphic relationships are accessed through the parent resource's relationship endpoints and includes. Route only the parent resource; the gem automatically handles polymorphic types through the relationship endpoints.
+
+```ruby
+# config/routes.rb
+jsonapi_resources :users
+```
+
+The user model declares a polymorphic `belongs_to`:
+
+```ruby
+class User < ActiveRecord::Base
+  belongs_to :profile, polymorphic: true
+end
+```
 
-The gem supports polymorphic associations (both `belongs_to :profile, polymorphic: true` and `has_many :activities, as: :actor`). When including polymorphic relationships, the serializer automatically determines the correct resource type based on the actual class of the related object:
+Define a resource class for each concrete type:
 
 ```ruby
-# User belongs_to :profile, polymorphic: true
-# User has_many :activities, as: :actor
+# app/resources/user_resource.rb
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+  has_one :profile  # auto-detected as polymorphic from model
+end
+
+# app/resources/admin_profile_resource.rb
+class AdminProfileResource < JSONAPI::Resource
+  attributes :department, :level
+end
 
-GET /users?include=profile
-GET /users?include=activities
-GET /users/:id?include=profile,activities
+# app/resources/customer_profile_resource.rb
+class CustomerProfileResource < JSONAPI::Resource
+  attributes :company_name, :industry
+end
 ```
 
-The response will include the correct resource type for each polymorphic association (e.g., `customer_profiles` or `admin_profiles` for a polymorphic `profile` association).
+The gem auto-detects polymorphism from the model's association. To override, use `polymorphic: true` explicitly.
 
-**Example Response with Polymorphic Relationship:**
+Responses use the concrete type. For example, a user with an admin profile returns the concrete type in the relationship data and `included` array:
+
+```http
+GET /users/1?include=profile HTTP/1.1
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
 
-```json
 {
-  "jsonapi": {
-    "version": "1.1"
-  },
   "data": {
     "type": "users",
     "id": "1",
-    "attributes": {
-      "name": "John Doe",
-      "email": "john@example.com",
-      "phone": "555-0100"
-    },
     "relationships": {
       "profile": {
-        "data": {
-          "type": "admin_profiles",
-          "id": "1"
-        }
+        "data": { "type": "admin_profiles", "id": "5" }
       }
-    },
-    "links": {
-      "self": "/users/1"
     }
   },
   "included": [
     {
       "type": "admin_profiles",
-      "id": "1",
-      "attributes": {
-        "department": "Engineering",
-        "level": "Senior"
-      },
-      "links": {
-        "self": "/admin_profiles/1"
-      }
+      "id": "5",
+      "attributes": { "department": "Engineering", "level": "Senior" }
     }
   ]
 }
 ```
 
-#### Single Table Inheritance (STI) Support
+When creating or updating, provide the concrete type in the relationship payload:
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "profile": {
+        "data": { "type": "customer_profiles", "id": "10" }
+      }
+    }
+  }
+}
+```
+
+If you need direct access to polymorphic resources (e.g., `GET /admin_profiles/1`), add explicit routes:
 
-The gem supports Single Table Inheritance (STI) resources and relationships. Subclasses are treated as first-class JSON:API resources with their own types, while sharing the underlying table.
+```ruby
+jsonapi_resources :admin_profiles
+jsonapi_resources :customer_profiles
+```
 
-##### Routing
+## Single Table Inheritance (STI)
 
-To enable STI support, use the `sti` option in your routes configuration. Pass an array of subtype names to generate routes for both the base resource and its subclasses:
+STI subclasses are treated as first-class JSON:API resources with their own types. Use the `sti` option in routes:
 
 ```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  # Generates routes for:
-  # - /notifications (Base resource)
-  # - /email_notifications
-  # - /sms_notifications
-  jsonapi_resources :notifications, sti: [:email_notifications, :sms_notifications]
-end
+jsonapi_resources :notifications, sti: [:email_notifications, :sms_notifications]
 ```
 
-##### Resource Definitions
+This generates:
+
+- `GET /notifications` — lists all notifications (index only)
+- `GET /email_notifications/:id`, `POST /email_notifications`, etc. — full CRUD for each subtype
+- `GET /sms_notifications/:id`, `POST /sms_notifications`, etc.
+
+The models use standard Rails STI inheritance:
+
+```ruby
+class Notification < ActiveRecord::Base
+  validates :subject, presence: true
+end
+
+class EmailNotification < Notification
+  validates :recipient_email, presence: true
+end
+
+class SmsNotification < Notification
+  validates :phone_number, presence: true
+end
+```
 
-Define a resource class for the base model and each subclass. Subclasses should inherit from the base resource class to share configuration:
+Subclass resources inherit attributes from the parent:
 
 ```ruby
-# app/resources/notification_resource.rb
 class NotificationResource < JSONAPI::Resource
-  attributes :body, :created_at
-  has_one :user
+  attributes :subject, :body
 end
 
-# app/resources/email_notification_resource.rb
 class EmailNotificationResource < NotificationResource
-  attributes :subject, :recipient_email
+  attributes :recipient_email  # inherits :subject, :body
 end
 
-# app/resources/sms_notification_resource.rb
 class SmsNotificationResource < NotificationResource
-  attributes :phone_number
+  attributes :phone_number  # inherits :subject, :body
 end
 ```
 
-##### Serialization
+The base endpoint returns all subtypes with their concrete types:
 
-Resources are serialized with their specific type. When querying the base endpoint (e.g., `GET /notifications`), the response will contain a mix of types:
+```http
+GET /notifications HTTP/1.1
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
 
-```json
 {
   "data": [
     {
       "type": "email_notifications",
       "id": "1",
       "attributes": {
-        "body": "Welcome!",
-        "subject": "Hello"
+        "subject": "Welcome",
+        "body": "...",
+        "recipient_email": "user@example.com"
       }
     },
     {
       "type": "sms_notifications",
       "id": "2",
       "attributes": {
-        "body": "Code: 1234",
+        "subject": "Alert",
+        "body": "...",
         "phone_number": "555-1234"
       }
     }
@@ -783,161 +411,54 @@ Resources are serialized with their specific type. When querying the base endpoi
 }
 ```
 
-##### Creating STI Resources
+To create or update, use the subtype endpoint with the concrete type:
 
-To create a specific subclass, send a POST request to either the base endpoint or the specific subclass endpoint, specifying the correct `type` in the payload:
-
-```json
-POST /notifications
+```http
+POST /email_notifications HTTP/1.1
 Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
 
 {
   "data": {
     "type": "email_notifications",
     "attributes": {
-      "subject": "Important",
-      "body": "Please read this.",
+      "subject": "Welcome",
+      "body": "Hello",
       "recipient_email": "user@example.com"
-    },
-    "relationships": {
-      "user": {
-        "data": { "type": "users", "id": "1" }
-      }
     }
   }
 }
 ```
 
-The controller automatically instantiates the correct model class based on the `type` field.
-
-#### STI resource DSL inheritance
-
-- Subclasses inherit parent DSL (attributes, filters, sortable_fields, relationships, creatable_fields, updatable_fields, class-level `meta`) only when they do **not** declare that DSL themselves.
-- Once a subclass calls a DSL method, it uses only its own declarations; it must opt-in to parent definitions explicitly (e.g., `attributes(*superclass.permitted_attributes, :child_attr)`).
-- Instance-level `meta` methods still inherit via Ruby method lookup; class-level `meta` follows the “silent inherits, declare resets” rule.
-- For sparse fieldsets, expose needed attributes on the subtype by including the parent set when you declare subtype DSL.
-
-#### Sorting
-
-Sorting is only available on index endpoints (collection endpoints). Use the `sort` parameter to specify one or more fields to sort by:
-
-```ruby
-# Sort by name ascending
-GET /users?sort=name
-
-# Sort by name descending (prefix with -)
-GET /users?sort=-name
-
-# Sort by multiple fields
-GET /users?sort=name,created_at
-
-# Sort by multiple fields with mixed directions
-GET /users?sort=name,-created_at
-```
-
-Invalid sort fields will return a `400 Bad Request` error with a JSON:API error response:
-
-```json
-{
-  "errors": [
-    {
-      "status": "400",
-      "title": "Invalid Sort Field",
-      "detail": "Invalid sort fields requested: invalid_field"
-    }
-  ]
-}
-```
-
-The sort parameter is ignored on show endpoints (single resource endpoints). However, relationship endpoints support sorting for collection relationships:
-
-```ruby
-# Sort posts relationship
-GET /users/:id/relationships/posts?sort=title,-created_at
-```
-
-Sorting on relationship endpoints validates against the related model's columns, not the parent resource.
-
-#### Virtual Attribute Sorting
+## Sorting
 
-The gem supports sorting by virtual attributes (attributes that don't correspond to database columns). When sorting by a virtual attribute, the gem:
+Sort collections with the `sort` parameter. Prefix with `-` for descending. Seperate multiple sorts with comma `,`:
 
-1. Loads all records into memory
-2. Sorts them in Ruby using the resource's getter method for the virtual attribute
-3. Recalculates the total count after sorting
-
-You can mix database columns and virtual attributes in the same sort:
-
-```ruby
-# Sort by database column first, then by virtual attribute
-GET /users?sort=name,full_name
+```http
+GET /users?sort=name,-created_at HTTP/1.1
+Accept: application/vnd.api+json
 ```
 
-**Example:**
+Virtual attributes can also be sorted (loaded into memory first). Declare sort-only fields with `sortable_fields` to allow sorting without exposing the value:
 
 ```ruby
-class UserResource < JSONAPI::Resource
-  attributes :name, :email, :full_name
-
-  def full_name
-    "#{resource.name} (#{resource.email})"
-  end
+class User < ActiveRecord::Base
+  has_many :posts
 end
 ```
 
-```ruby
-# Sort by virtual attribute ascending
-GET /users?sort=full_name
-
-# Sort by virtual attribute descending
-GET /users?sort=-full_name
-
-# Mix database column and virtual attribute
-GET /users?sort=name,full_name
-```
-
-**Performance Note**: Sorting by virtual attributes requires loading all matching records into memory. For large collections, consider using database columns or computed database columns instead.
-
-#### Sort-Only Fields
-
-You can declare virtual fields that are sortable but not exposed as attributes. This is useful when you want to allow sorting by a computed value without making it readable or writable in the API response.
-
-To declare a sort-only field, use `sortable_fields` in your resource class and implement a getter method:
-
 ```ruby
 class UserResource < JSONAPI::Resource
   attributes :name, :email
-
-  # Declare sort-only field
   sortable_fields :posts_count
 
-  # Implement getter method (same as virtual attribute)
   def posts_count
     resource.posts.size
   end
 end
 ```
 
-Sort-only fields:
-
-- Can be used in sort parameters: `GET /users?sort=posts_count`
-- Are validated as valid sort fields
-- Are NOT included in serialized attributes
-- Can be mixed with database columns and regular attributes in sort parameters
-
-**Example:**
-
-```ruby
-# Sort by sort-only field
-GET /users?sort=posts_count
-
-# Mix sort-only field with database column
-GET /users?sort=posts_count,name
-```
-
-**Note**: Sort-only fields still require loading records into memory for sorting, just like virtual attributes. The difference is that sort-only fields won't appear in the response attributes.
-
-### JSON:API Object
+## JSON:API Object
 
 All responses automatically include a `jsonapi` object indicating JSON:API version compliance:
 
@@ -950,60 +471,63 @@ All responses automatically include a `jsonapi` object indicating JSON:API versi
 }
 ```
 
-You can customize the jsonapi object via configuration:
+The version is hardcoded to "1.1". You can add meta information to the jsonapi object via configuration:
 
 ```ruby
 # config/initializers/json_api.rb
 JSONAPI.configure do |config|
-  config.jsonapi_version = "1.1"
   config.jsonapi_meta = { ext: ["https://jsonapi.org/ext/atomic"] }
 end
 ```
 
-### Meta Information
+## Meta Information
 
 The gem supports meta information at three levels: document-level, resource-level, and relationship-level.
 
-#### Document-Level Meta
+### Document-Level Meta
+
+Document-level meta appears at the top level of the response. Pagination automatically includes `total` when pagination is applied.
+
+To add custom document-level meta globally, configure `document_meta_resolver`:
+
+```ruby
+JSONAPI.configure do |config|
+  config.document_meta_resolver = lambda do |controller:|
+    {
+      request_id: controller.request.request_id,
+      api_version: "v1"
+    }
+  end
+end
+```
 
-Document-level meta appears at the top level of the response and is typically used for pagination:
+The resolver receives the controller instance and returns a hash that is merged with pagination meta:
 
 ```json
 {
   "jsonapi": { "version": "1.1" },
-  "data": [ ... ],
+  "data": [...],
   "meta": {
+    "request_id": "abc-123",
+    "api_version": "v1",
     "total": 100
   }
 }
 ```
 
-Pagination automatically includes meta with the total count when pagination is applied.
+For per-controller customization, override `jsonapi_document_meta` in a custom controller:
 
-**Example Document-Level Meta:**
+```ruby
+class Api::UsersController < JSONAPI::ResourcesController
+  private
 
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "data": [
-    {
-      "type": "users",
-      "id": "1",
-      "attributes": {
-        "name": "John Doe",
-        "email": "john@example.com"
-      }
-    }
-  ],
-  "meta": {
-    "total": 100
-  }
-}
+  def jsonapi_document_meta(extra_meta = {})
+    super(extra_meta.merge(custom_field: "value"))
+  end
+end
 ```
 
-#### Resource-Level Meta
+### Resource-Level Meta
 
 Resource-level meta appears within each resource object. By default, the gem automatically includes `created_at` and `updated_at` timestamps in ISO8601 format if the model responds to these methods.
 
@@ -1063,7 +587,7 @@ The instance method has access to the model instance via `resource`. Custom meta
 }
 ```
 
-#### Relationship-Level Meta
+### Relationship-Level Meta
 
 Relationship-level meta appears within relationship objects:
 
@@ -1111,272 +635,89 @@ The response will include:
         }
       }
     },
-    "links": {
-      "self": "/users/1"
-    }
-  }
-}
-```
-
-### Configuration
-
-Configure the gem in an initializer:
-
-```ruby
-# config/initializers/json_api.rb
-JSONAPI.configure do |config|
-  config.default_page_size = 25
-  config.max_page_size = 100
-  config.jsonapi_version = "1.1"
-  config.jsonapi_meta = nil
-  config.base_controller_class = ActionController::API  # Default: ActionController::API
-end
-```
-
-#### Base Controller Class
-
-By default, `JSONAPI::BaseController` inherits from `ActionController::API`. You can configure it to inherit from a different base class (e.g., `ActionController::Base` or a custom base controller):
-
-```ruby
-JSONAPI.configure do |config|
-  # Use ActionController::Base instead of ActionController::API
-  config.base_controller_class = ActionController::Base
-
-  # Or use a custom base controller
-  config.base_controller_class = ApplicationController
-end
-```
-
-This is useful when you need access to features available in `ActionController::Base` that aren't in `ActionController::API`, such as:
-
-- View rendering helpers
-- Layout support
-- Cookie-based sessions
-- Flash messages
-
-**Note:** The configuration must be set before the gem's controllers are loaded. Set it in a Rails initializer that loads before `json_api` is required.
-
-### Authorization
-
-The gem provides configurable authorization hooks that allow you to integrate with any authorization library (e.g., Pundit, CanCanCan). Authorization is handled through two hooks:
-
-- **`authorization_scope`**: Filters collection queries (index actions) to only return records the user is authorized to see
-- **`authorization_handler`**: Authorizes individual actions (show, create, update, destroy) on specific records
-
-Both hooks are optional - if not configured, all records are accessible (authorization is bypassed).
-
-#### Authorization Scope Hook
-
-The `authorization_scope` hook receives the initial ActiveRecord scope and should return a filtered scope containing only records the user is authorized to access:
-
-```ruby
-JSONAPI.configure do |config|
-  config.authorization_scope = lambda do |controller:, scope:, action:, model_class:|
-    # Filter the scope based on authorization logic
-    # For example, only return records belonging to the current user
-    scope.where(user_id: controller.current_user.id)
-  end
-end
-```
-
-**Parameters:**
-
-- `controller`: The controller instance (provides access to `current_user`, `params`, etc.)
-- `scope`: The initial ActiveRecord scope (e.g., `User.all` or preloaded resources)
-- `action`: The action being performed (`:index`)
-- `model_class`: The ActiveRecord model class (e.g., `User`)
-
-**Return value:** An ActiveRecord scope containing only authorized records
-
-#### Authorization Handler Hook
-
-The `authorization_handler` hook is called for individual resource actions (show, create, update, destroy) and should raise an exception if the user is not authorized:
-
-```ruby
-JSONAPI.configure do |config|
-  config.authorization_handler = lambda do |controller:, record:, action:, context: nil|
-    # Raise an exception if the user is not authorized
-    unless authorized?(controller.current_user, record, action)
-      raise JSONAPI::AuthorizationError, "Not authorized to #{action} this resource"
-    end
-  end
-end
-```
-
-**Parameters:**
-
-- `controller`: The controller instance
-- `record`: The ActiveRecord record being accessed (for create, this is a new unsaved record)
-- `action`: The action being performed (`:show`, `:create`, `:update`, or `:destroy`)
-- `context`: Optional context hash (for relationship actions, includes `relationship:` key)
-
-**Exceptions:** Raise `JSONAPI::AuthorizationError` to deny access. Your application is responsible for rescuing this error and rendering an appropriate response (e.g., a `403 Forbidden` JSON:API error object).
-
-#### Pundit Integration Example
-
-Here's a complete example using Pundit:
-
-```ruby
-# config/initializers/json_api_authorization.rb
-
-# Include Pundit in JSONAPI::BaseController
-JSONAPI::BaseController.class_eval do
-  include Pundit::Authorization
-
-  rescue_from JSONAPI::AuthorizationError, with: :render_jsonapi_authorization_error
-
-  # Provide current_user method (override in your application)
-  def current_user
-    # Return the current authenticated user
-    # This is application-specific
-    @current_user ||= User.find_by(id: session[:user_id]) if session[:user_id]
-  end
-
-  private
-
-  def render_jsonapi_authorization_error(error)
-    detail = error&.message.presence || "You are not authorized to perform this action"
-    render json: {
-      errors: [
-        {
-          status: "403",
-          title: "Forbidden",
-          detail:
-        }
-      ]
-    }, status: :forbidden
-  end
-end
-
-# Configure JSON:API authorization hooks using Pundit
-JSONAPI.configure do |config|
-  # Authorization scope hook - filters collections based on Pundit scopes
-  config.authorization_scope = lambda do |controller:, scope:, action:, model_class:|
-    policy_class = Pundit::PolicyFinder.new(model_class).policy
-    policy_scope = policy_class.const_get(:Scope).new(controller.current_user, scope)
-    policy_scope.resolve
-  end
-
-  # Authorization handler hook - authorizes individual actions using Pundit policies
-  # Note: We convert Pundit authorization failures to JSONAPI::AuthorizationError
-  # so the gem can handle them consistently
-  config.authorization_handler = lambda do |controller:, record:, action:, context: nil|
-    policy_class = Pundit::PolicyFinder.new(record).policy
-    policy = policy_class.new(controller.current_user, record)
-
-    action_method = "#{action}?"
-    unless policy.public_send(action_method)
-      raise JSONAPI::AuthorizationError, "Not authorized to #{action} this resource"
-    end
-  end
-end
-```
-
-**Example Policy:**
-
-```ruby
-# app/policies/user_policy.rb
-class UserPolicy < ApplicationPolicy
-  def index?
-    true
-  end
-
-  def show?
-    record.public? || user == record
-  end
-
-  def create?
-    user.admin?
-  end
+    "links": {
+      "self": "/users/1"
+    }
+  }
+}
+```
 
-  def update?
-    user.admin? || user == record
-  end
+## Configuration
 
-  def destroy?
-    user.admin?
-  end
+Configure the gem in an initializer:
 
-  class Scope < ApplicationPolicy::Scope
-    def resolve
-      if user.admin?
-        scope.all
-      else
-        scope.where(public: true).or(scope.where(id: user.id))
-      end
-    end
-  end
+```ruby
+# config/initializers/json_api.rb
+JSONAPI.configure do |config|
+  config.default_page_size = 25
+  config.max_page_size = 100
+  config.jsonapi_meta = nil
+  config.base_controller_class = ActionController::API  # Default: ActionController::API
 end
 ```
 
-#### Relationship Authorization
+### Base Controller Class
 
-Relationship endpoints (show, update, destroy) authorize the parent resource using the `:update` action with a context hash containing the relationship name:
+By default, `JSONAPI::BaseController` inherits from `ActionController::API`. You can configure it to inherit from a different base class (e.g., `ActionController::Base` or a custom base controller):
 
 ```ruby
-# The authorization_handler receives:
-{
-  controller: controller_instance,
-  record: parent_resource,
-  action: :update,
-  context: { relationship: :posts }
-}
+JSONAPI.configure do |config|
+  # Use ActionController::Base instead of ActionController::API
+  config.base_controller_class = ActionController::Base
+
+  # Or use a custom base controller
+  config.base_controller_class = ApplicationController
+end
 ```
 
-This allows you to implement relationship-specific authorization logic in your policies if needed.
+This is useful when you need access to features available in `ActionController::Base` that aren't in `ActionController::API`, such as:
 
-#### Custom Authorization Error Handling
+- View rendering helpers
+- Layout support
+- Cookie-based sessions
+- Flash messages
 
-The gem automatically handles `JSONAPI::AuthorizationError` and `Pundit::NotAuthorizedError` exceptions, rendering a JSON:API compliant `403 Forbidden` response:
+**Note:** The configuration must be set before the gem's controllers are loaded. Set it in a Rails initializer that loads before `json_api` is required.
 
-```json
-{
-  "jsonapi": {
-    "version": "1.1"
-  },
-  "errors": [
-    {
-      "status": "403",
-      "title": "Forbidden",
-      "detail": "You are not authorized to perform this action"
-    }
-  ]
-}
-```
+## Authorization
 
-You can customize the error message by raising an exception with a specific message:
+The gem provides two optional authorization hooks:
 
-```ruby
-raise JSONAPI::AuthorizationError, "Not authorized to view this resource"
-```
+- `authorization_scope` — filters collections (index) to authorized records
+- `authorization_handler` — authorizes individual actions (show, create, update, destroy)
 
-#### Overriding Authorization
+If not configured, authorization is bypassed.
 
-Authorization hooks can be easily overridden or disabled:
+### Pundit Integration
 
 ```ruby
-# Disable authorization (allow all access)
+# config/initializers/json_api.rb
 JSONAPI.configure do |config|
-  config.authorization_scope = nil
-  config.authorization_handler = nil
-end
+  config.authorization_scope = lambda do |controller:, scope:, action:, model_class:|
+    policy_class = Pundit::PolicyFinder.new(model_class).policy
+    policy_scope = policy_class.const_get(:Scope).new(controller.current_user, scope)
+    policy_scope.resolve
+  end
 
-# Use custom authorization logic
-JSONAPI.configure do |config|
   config.authorization_handler = lambda do |controller:, record:, action:, context: nil|
-    # Your custom authorization logic here
-    unless MyAuthService.authorized?(controller.current_user, record, action)
-      raise JSONAPI::AuthorizationError, "Access denied"
+    policy_class = Pundit::PolicyFinder.new(record).policy
+    policy = policy_class.new(controller.current_user, record)
+    unless policy.public_send("#{action}?")
+      raise JSONAPI::AuthorizationError, "Not authorized to #{action} this resource"
     end
   end
 end
 ```
 
-### Instrumentation (Rails 8.1+)
+The gem automatically renders `403 Forbidden` for `JSONAPI::AuthorizationError` and `Pundit::NotAuthorizedError`.
+
+Relationship endpoints authorize the parent resource with `action: :update` and `context: { relationship: :relationship_name }`.
+
+## Instrumentation (Rails 8.1+)
 
 When running on Rails 8.1 or later, the gem automatically emits structured events via `Rails.event` for all CRUD and relationship operations. This enables seamless integration with monitoring and APM platforms like Datadog, AppSignal, New Relic, or Honeycomb.
 
-#### Resource Events
+### Resource Events
 
 The gem emits events for resource lifecycle operations:
 
@@ -1409,7 +750,7 @@ end
 Rails.event.subscribe(JsonApiEventSubscriber.new) if Rails.respond_to?(:event)
 ```
 
-#### Relationship Events
+### Relationship Events
 
 The gem also emits events for relationship operations:
 
@@ -1428,7 +769,7 @@ The gem also emits events for relationship operations:
 }
 ```
 
-#### Testing Instrumentation
+### Testing Instrumentation
 
 Use Rails 8.1's `assert_events_reported` test helper to verify events are emitted:
 
@@ -1441,33 +782,7 @@ assert_events_reported([
 end
 ```
 
-#### Compatibility
-
-The instrumentation feature is automatically enabled when `Rails.event` is available (Rails 8.1+). On older Rails versions, the gem continues to work normally without emitting events. No configuration is required.
-
-### Creatable and Updatable Fields
-
-By default, all attributes defined with `attributes` are available for both create and update operations. You can restrict which fields can be created or updated separately:
-
-```ruby
-class UserResource < JSONAPI::Resource
-  attributes :name, :email, :phone, :role
-
-  # Only these fields can be set during creation
-  creatable_fields :name, :email, :phone
-
-  # Only these fields can be updated
-  updatable_fields :name, :phone
-end
-```
-
-If `creatable_fields` or `updatable_fields` are not explicitly defined, the gem defaults to using all `permitted_attributes`. This allows you to:
-
-- Prevent certain fields from being set during creation (e.g., `role` might be set by the system)
-- Prevent certain fields from being updated (e.g., `email` might be immutable after creation)
-- Have different field sets for create vs update operations
-
-### Content Negotiation
+## Content Negotiation
 
 The gem enforces JSON:API content negotiation:
 
@@ -1476,7 +791,7 @@ The gem enforces JSON:API content negotiation:
 
 Blank or `*/*` Accept headers are allowed to support browser defaults.
 
-### Custom Controllers
+## Custom Controllers
 
 You can inherit from `JSONAPI::BaseController` to create custom controllers:
 
@@ -1499,7 +814,7 @@ The base controller provides helper methods:
 - `parse_sort_param` - Parsed sort parameter
 - `parse_page_param` - Parsed page parameter
 
-### Serialization
+## Serialization
 
 Use `JSONAPI::Serializer` to serialize resources:
 
@@ -1508,7 +823,7 @@ serializer = JSONAPI::Serializer.new(user)
 serializer.to_hash(include: ["posts"], fields: { users: ["name", "email"] })
 ```
 
-### Deserialization
+## Deserialization
 
 Use `JSONAPI::Deserializer` to deserialize JSON:API payloads:
 
@@ -1525,12 +840,15 @@ The deserializer automatically converts JSON:API relationship format to Rails-fr
 - To-one relationships: `account` → `account_id`
 - Polymorphic relationships: `profile` → `profile_id` and `profile_type`
 
-#### Creating Resources with Relationships
+### Creating Resources with Relationships
 
 You can include relationships when creating resources:
 
-```ruby
-# POST /users
+```http
+POST /users HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
 {
   "data": {
     "type": "users",
@@ -1556,12 +874,15 @@ You can include relationships when creating resources:
 }
 ```
 
-#### Updating Resources with Relationships
+### Updating Resources with Relationships
 
 You can update relationships when updating resources:
 
-```ruby
-# PATCH /users/:id
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
 {
   "data": {
     "type": "users",
@@ -1586,12 +907,15 @@ You can update relationships when updating resources:
 }
 ```
 
-#### Clearing Relationships
+### Clearing Relationships
 
 To clear a relationship, send `null` for to-one relationships or an empty array for to-many relationships:
 
-```ruby
-# Clear to-one relationship
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
 {
   "data": {
     "type": "users",
@@ -1603,8 +927,13 @@ To clear a relationship, send `null` for to-one relationships or an empty array
     }
   }
 }
+```
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
 
-# Clear to-many relationship
 {
   "data": {
     "type": "users",
@@ -1618,7 +947,7 @@ To clear a relationship, send `null` for to-one relationships or an empty array
 }
 ```
 
-#### Relationship Validation
+### Relationship Validation
 
 The gem validates relationship data:
 
@@ -1627,14 +956,15 @@ The gem validates relationship data:
 - Invalid polymorphic type (class doesn't exist) returns `400 Bad Request`
 - Attempting to unset linkage that cannot be nullified (e.g., foreign key has NOT NULL constraint) returns `400 Bad Request`
 
-### Relationship Endpoints
+## Relationship Endpoint Details
 
 The gem provides dedicated endpoints for managing relationships independently of the main resource:
 
-#### Show Relationship
+### Show Relationship
 
-```ruby
-GET /users/:id/relationships/posts
+```http
+GET /users/1/relationships/posts HTTP/1.1
+Accept: application/vnd.api+json
 ```
 
 Returns the relationship data (resource identifiers) with links and meta:
@@ -1695,15 +1025,17 @@ Returns the relationship data (resource identifiers) with links and meta:
 
 For collection relationships, you can sort using the `sort` parameter:
 
-```ruby
-GET /users/:id/relationships/posts?sort=title,-created_at
+```http
+GET /users/1/relationships/posts?sort=title,-created_at HTTP/1.1
+Accept: application/vnd.api+json
 ```
 
-#### Update Relationship
+### Update Relationship
 
-```ruby
-PATCH /users/:id/relationships/posts
+```http
+PATCH /users/1/relationships/posts HTTP/1.1
 Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
 
 {
   "data": [
@@ -1715,11 +1047,12 @@ Content-Type: application/vnd.api+json
 
 Replaces the entire relationship linkage. For to-one relationships, send a single resource identifier object (or `null` to clear). For to-many relationships, send an array of resource identifiers (or empty array `[]` to clear).
 
-#### Delete Relationship Linkage
+### Delete Relationship Linkage
 
-```ruby
-DELETE /users/:id/relationships/posts
+```http
+DELETE /users/1/relationships/posts HTTP/1.1
 Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
 
 {
   "data": [
@@ -1799,356 +1132,463 @@ Error responses follow JSON:API error format:
 }
 ```
 
-## Development
+## ActiveStorage Support
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+The gem automatically detects and serializes ActiveStorage attachments when exposed as relationships.
 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Exposing Attachments
 
-### Code Organization
+Declare ActiveStorage attachments as relationships in your resource:
 
-The gem is organized into several directories within `lib/json_api/`:
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+  has_many_attached :documents
+end
 
-- **`controllers/`** - Controller classes (`BaseController`, `ResourcesController`, `RelationshipsController`)
-- **`resources/`** - Resource DSL and resource loading (`Resource`, `ResourceLoader`, `ActiveStorageBlobResource`)
-- **`serialization/`** - Serialization and deserialization (`Serializer`, `Deserializer`)
-- **`support/`** - Shared concerns and utilities:
-  - `ActiveStorageSupport` - Concern for handling ActiveStorage attachments
-  - `CollectionQuery` - Service class for building filtered, sorted, and paginated queries
-  - `RelationshipHelpers` - Utilities for relationship handling
-  - `ParamHelpers` - Parameter parsing utilities
-  - `Responders` - Content negotiation and error rendering
-  - `Instrumentation` - Rails event emission
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+  has_one :avatar
+  has_many :documents
+end
+```
 
-This organization makes it easier to understand the gem's structure and locate specific functionality.
+The gem auto-detects these are ActiveStorage attachments and serializes them as `active_storage_blobs` relationships:
 
-## Testing
+```http
+GET /users/1?include=avatar HTTP/1.1
+Accept: application/vnd.api+json
 
-Run the test suite:
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
 
-```bash
-bundle exec rspec
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": { "name": "John Doe", "email": "john@example.com" },
+    "relationships": {
+      "avatar": { "data": { "type": "active_storage_blobs", "id": "1" } },
+      "documents": { "data": [
+        { "type": "active_storage_blobs", "id": "2" },
+        { "type": "active_storage_blobs", "id": "3" }
+      ]}
+    }
+  },
+  "included": [{
+    "type": "active_storage_blobs",
+    "id": "1",
+    "attributes": {
+      "filename": "avatar.jpg",
+      "content_type": "image/jpeg",
+      "byte_size": 102400,
+      "checksum": "abc123...",
+      "url": "/rails/active_storage/blobs/.../avatar.jpg"
+    },
+    "links": {
+      "self": "/active_storage_blobs/1",
+      "download": "/rails/active_storage/blobs/.../avatar.jpg"
+    }
+  }]
+}
 ```
 
-### Test Helper for Request Specs
+The built-in `JSONAPI::ActiveStorageBlobResource` provides `filename`, `content_type`, `byte_size`, `checksum`, and `url` attributes, plus a download link.
 
-The gem provides a test helper module that makes it easy to write request specs with proper JSON:API content negotiation. The helper ensures `as: :jsonapi` works consistently across all HTTP methods.
+### Attaching Files
 
-**Setup (RSpec):**
+Clients attach files by providing signed blob IDs from ActiveStorage direct uploads:
 
-```ruby
-# spec/rails_helper.rb or spec/support/json_api.rb
-require "json_api/testing"
+```http
+POST /users HTTP/1.1
+Content-Type: application/vnd.api+json
 
-RSpec.configure do |config|
-  config.include JSONAPI::Testing::TestHelper, type: :request
-end
+{
+  "data": {
+    "type": "users",
+    "attributes": { "name": "Jane Doe", "email": "jane@example.com" },
+    "relationships": {
+      "avatar": { "data": { "type": "active_storage_blobs", "id": "eyJfcmFpbHMi..." } },
+      "documents": { "data": [
+        { "type": "active_storage_blobs", "id": "signed-id-1" },
+        { "type": "active_storage_blobs", "id": "signed-id-2" }
+      ]}
+    }
+  }
+}
 ```
 
-**Usage:**
+The deserializer validates signed IDs via `ActiveStorage::Blob.find_signed!` and converts them to blob objects for attachment. Invalid signed IDs raise `ActiveSupport::MessageVerifier::InvalidSignature`.
 
-```ruby
-RSpec.describe "Users API", type: :request do
-  let(:headers) { { "Authorization" => "Bearer #{token}" } }
-
-  describe "GET /users" do
-    it "returns users" do
-      # GET requests: Accept header is set, params go to query string
-      get users_path, params: { filter: { active: true } }, headers:, as: :jsonapi
-      expect(response).to have_http_status(:ok)
-    end
-  end
+### Detaching Files
 
-  describe "POST /users" do
-    it "creates a user" do
-      # POST/PATCH/PUT/DELETE: Content-Type and Accept headers are set,
-      # params are JSON-encoded in the request body
-      payload = {
-        data: {
-          type: "users",
-          attributes: { name: "John", email: "john@example.com" }
-        }
-      }
-      post users_path, params: payload, headers:, as: :jsonapi
-      expect(response).to have_http_status(:created)
-    end
-  end
-end
-```
+Send `null` or `[]` to detach attachments:
 
-**Behavior by HTTP method:**
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
 
-| Method | Accept Header | Content-Type Header | Params Encoding |
-| ------ | ------------- | ------------------- | --------------- |
-| GET    | ✅ Set        | ❌ Not set          | Query string    |
-| POST   | ✅ Set        | ✅ Set              | JSON body       |
-| PATCH  | ✅ Set        | ✅ Set              | JSON body       |
-| PUT    | ✅ Set        | ✅ Set              | JSON body       |
-| DELETE | ✅ Set        | ✅ Set              | JSON body       |
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "avatar": { "data": null },
+      "documents": { "data": [] }
+    }
+  }
+}
+```
 
-### Integration Tests
+By default, this purges the attachments. For has_one, sending `null` detaches. For has_many, sending `[]` removes all.
 
-The gem includes a dummy Rails app in `spec/dummy` for integration testing. The integration tests verify that the gem works correctly with a real Rails application.
+### Relationship Options
 
-To run only integration tests:
+**`purge_on_nil`** (default: `true`) — Controls whether attachments are purged when set to `null`/`[]`:
 
-```bash
-bundle exec rspec spec/integration
+```ruby
+has_one :avatar, purge_on_nil: false   # Keep existing when null
+has_many :documents, purge_on_nil: false
 ```
 
-The integration tests cover:
+**`append_only`** (has_many only, default: `false`) — Append new blobs instead of replacing:
 
-- Full CRUD operations (create, read, update, delete)
-- JSON:API response format validation using JSON Schema
-- Sparse fieldsets (fields parameter) for single and multiple fields
-- Sorting (ascending, descending, multiple fields, invalid fields)
-- Including related resources (include parameter) with validation
-- Creating and updating resources with relationships (to-one, to-many, polymorphic)
-- Relationship validation and error handling
-- Error handling and validation responses
-- HTTP status codes
+```ruby
+has_many :documents, append_only: true
+```
 
-The dummy app includes a simple `User` model with basic validations and relationships (posts, profile, activities, notifications) to test the full request/response cycle including relationship writes.
+When enabled:
 
-## ActiveStorage Support
+- New blobs append to existing: `[blob1, blob2] + [blob3] → [blob1, blob2, blob3]`
+- Empty array `[]` is a no-op (preserves existing)
+- Implicitly sets `purge_on_nil: false`
+- Remove attachments via the DELETE relationship endpoint
 
-The gem includes built-in support for serializing and deserializing ActiveStorage attachments through JSON:API.
+These options are mutually exclusive — `append_only: true` with `purge_on_nil: true` raises `ArgumentError`.
 
-### Serializing Attachments
+## Client Integration: devour-client-ts
 
-When a model has ActiveStorage attachments (`has_one_attached` or `has_many_attached`), you can expose them as relationships in your resource:
+The `devour-client-ts` npm package is a TypeScript JSON:API client that works seamlessly with this gem. This section covers how to configure and use devour-client-ts as a frontend client.
 
-```ruby
-class UserResource < JSONAPI::Resource
-  attributes :name, :email
-  has_one :avatar  # For has_one_attached :avatar
-  has_many :documents  # For has_many_attached :documents
-end
+### Installation
+
+```bash
+npm install devour-client-ts
 ```
 
-The serializer will automatically:
+### Basic Client Setup
 
-- Include attachment relationships pointing to `active_storage_blobs` resources
-- Add download links for each blob
-- Include blob details in the `included` section when requested via `include` parameter
-- Filter out ActiveStorage attachments from include paths (attachments are loaded on-demand by the serializer, not via ActiveRecord includes)
+```typescript
+import { JsonApi } from "devour-client-ts";
 
-Example response:
+const api = new JsonApi({
+  apiUrl: "http://localhost:3000",
+  headers: {
+    "Content-Type": "application/vnd.api+json",
+    Accept: "application/vnd.api+json",
+  },
+  trailingSlash: false, // Rails doesn't use trailing slashes
+  resetBuilderOnCall: true, // Prevent state pollution between calls
+});
+```
 
-```json
-{
-  "data": {
-    "type": "users",
-    "id": "1",
-    "attributes": {
-      "name": "John Doe",
-      "email": "john@example.com"
+### Defining Models
+
+Define models that match your Rails resources. Model names are singular, but `collectionPath` should be plural to match JSON:API conventions:
+
+```typescript
+// Simple model
+api.define(
+  "user",
+  {
+    email: {},
+    name: {},
+    phone: {},
+  },
+  {
+    collectionPath: "users",
+  }
+);
+
+// Model with relationships
+api.define(
+  "post",
+  {
+    title: {},
+    body: {},
+    user: {
+      jsonApi: "hasOne",
+      type: "users", // Must be plural
     },
-    "relationships": {
-      "avatar": {
-        "data": {
-          "type": "active_storage_blobs",
-          "id": "1"
-        }
-      },
-      "documents": {
-        "data": [
-          { "type": "active_storage_blobs", "id": "2" },
-          { "type": "active_storage_blobs", "id": "3" }
-        ]
-      }
+    comments: {
+      jsonApi: "hasMany",
+      type: "comments", // Must be plural
     },
-    "links": {
-      "self": "/users/1"
-    }
   },
-  "included": [
-    {
-      "type": "active_storage_blobs",
-      "id": "1",
-      "attributes": {
-        "filename": "avatar.jpg",
-        "content_type": "image/jpeg",
-        "byte_size": 102400,
-        "checksum": "abc123..."
-      },
-      "links": {
-        "self": "/active_storage_blobs/1",
-        "download": "/rails/active_storage/blobs/.../avatar.jpg"
-      }
-    }
-  ]
-}
+  {
+    collectionPath: "posts",
+  }
+);
 ```
 
-### Deserializing Attachments
+**Important**: All relationship `type` values must be **plural** to match JSON:API specification. Using singular types (e.g., `type: 'user'`) will cause "Type Mismatch" errors.
 
-When creating or updating resources, clients can attach files by providing signed blob IDs obtained from ActiveStorage direct uploads:
+### CRUD Operations
 
-```json
-{
-  "data": {
-    "type": "users",
-    "attributes": {
-      "name": "Jane Doe",
-      "email": "jane@example.com"
-    },
-    "relationships": {
-      "avatar": {
-        "data": {
-          "type": "active_storage_blobs",
-          "id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--..."
-        }
-      },
-      "documents": {
-        "data": [
-          { "type": "active_storage_blobs", "id": "signed-id-1" },
-          { "type": "active_storage_blobs", "id": "signed-id-2" }
-        ]
-      }
-    }
-  }
-}
+**Find all resources:**
+
+```typescript
+const { data: users } = await api.findAll("user").toPromise();
 ```
 
-The deserializer will:
+**Find a single resource:**
 
-- Validate the signed blob IDs
-- Convert them to blob objects
-- Set them as parameters that ActiveStorage can attach (e.g., `avatar: blob` or `documents: [blob1, blob2]`)
+```typescript
+const { data: user } = await api.find("user", "123").toPromise();
+```
 
-#### Detaching Attachments
+**Find with relationships:**
 
-To detach (remove) an attachment, send `null` for to-one relationships or an empty array `[]` for to-many relationships:
+```typescript
+const { data: user } = await api
+  .find("user", "123", {
+    include: ["posts", "profile"],
+  })
+  .toPromise();
 
-```json
-{
-  "data": {
-    "type": "users",
-    "id": "1",
-    "relationships": {
-      "avatar": {
-        "data": null
-      },
-      "documents": {
-        "data": []
-      }
-    }
-  }
-}
+// Relationships are deserialized onto the resource
+console.log(user.posts); // Array of post objects
+console.log(user.profile); // Profile object
 ```
 
-By default, this will purge the attachments from the model. For to-one attachments, sending `null` detaches the current attachment. For to-many attachments, sending an empty array `[]` removes all attachments.
+**Create a resource:**
 
-#### Controlling Purge Behavior with `purge_on_nil`
+```typescript
+const { data: newUser } = await api
+  .create("user", {
+    name: "John Doe",
+    email: "john@example.com",
+  })
+  .toPromise();
+```
 
-By default, when you set an attachment relationship to `null` (for `has_one_attached`) or an empty array `[]` (for `has_many_attached`), the gem will purge the existing attachments. You can opt out of this behavior by setting `purge_on_nil: false` in the relationship declaration:
+**Create with relationships:**
 
-```ruby
-class UserResource < JSONAPI::Resource
-  attributes :name, :email
+```typescript
+const { data: newPost } = await api
+  .create("post", {
+    title: "My Post",
+    body: "Content here",
+    user: { id: "123", type: "users" }, // hasOne - single object
+  })
+  .toPromise();
+```
 
-  # Opt out of purging when set to nil
-  has_one :avatar, purge_on_nil: false
-  has_many :documents, purge_on_nil: false
-end
+**Update a resource:**
+
+```typescript
+const { data: updated } = await api
+  .update("user", {
+    id: "123",
+    name: "Updated Name",
+  })
+  .toPromise();
 ```
 
-When `purge_on_nil: false` is set:
+**Delete a resource:**
 
-- Setting a `has_one_attached` relationship to `null` will keep the existing attachment
-- Setting a `has_many_attached` relationship to an empty array `[]` will keep all existing attachments
-- Attaching new blobs will still replace existing attachments (this behavior is not affected by `purge_on_nil`)
+```typescript
+await api.destroy("user", "123").toPromise();
+```
 
-**Use cases for `purge_on_nil: false`:**
+### Query Parameters
 
-- When you want to prevent accidental deletion of attachments
-- When attachments should only be removed through explicit delete operations
-- When you need more control over attachment lifecycle management
+**Filtering:**
 
-**Note:** The default behavior (`purge_on_nil: true`) ensures that setting a relationship to `null` or `[]` actually removes the attachments, which is typically the expected behavior for most use cases.
+```typescript
+const { data: users } = await api
+  .findAll("user", {
+    filter: {
+      name_eq: "John",
+      created_at_gte: "2024-01-01",
+    },
+  })
+  .toPromise();
+```
 
-#### Append-Only Mode with `append_only`
+**Sorting:**
 
-For `has_many_attached` relationships, you can enable append-only mode by setting `append_only: true`. In this mode, new blobs are appended to existing attachments rather than replacing them:
+```typescript
+const { data: users } = await api
+  .findAll("user", {
+    sort: "name", // Single field ascending
+  })
+  .toPromise();
 
-```ruby
-class UserResource < JSONAPI::Resource
-  attributes :name, :email
+const { data: users } = await api
+  .findAll("user", {
+    sort: "-created_at", // Descending (prefix with -)
+  })
+  .toPromise();
 
-  # Enable append-only mode for documents
-  has_many :documents, append_only: true
-end
+const { data: users } = await api
+  .findAll("user", {
+    sort: ["name", "-created_at"], // Multiple fields
+  })
+  .toPromise();
 ```
 
-**Behavior when `append_only: true` is set:**
+**Pagination:**
+
+```typescript
+const { data: users, meta } = await api
+  .findAll("user", {
+    page: {
+      number: 1,
+      size: 10,
+    },
+  })
+  .toPromise();
 
-- **Appending new blobs:** When updating a resource with new blobs in the relationship, they are added to the existing attachments instead of replacing them
+console.log(meta.total); // Total count
+```
 
-  ```json
-  // Existing attachments: [blob1, blob2]
-  // Payload includes: [blob3, blob4]
-  // Result: [blob1, blob2, blob3, blob4]
-  ```
+**Sparse fieldsets:**
 
-- **Empty array is a no-op:** Sending an empty array `[]` preserves all existing attachments
+```typescript
+const { data: users } = await api
+  .findAll("user", {
+    fields: {
+      users: ["name", "email"],
+      posts: ["title"],
+    },
+  })
+  .toPromise();
+```
 
-  ```json
-  // Existing attachments: [blob1, blob2]
-  // Payload includes: []
-  // Result: [blob1, blob2] (unchanged)
-  ```
+**Including related resources:**
 
-- **Implicit `purge_on_nil: false`:** When `append_only: true` is set, `purge_on_nil` is automatically set to `false` and cannot be overridden
+```typescript
+const { data: user } = await api
+  .find("user", "123", {
+    include: ["posts", "posts.comments"],
+  })
+  .toPromise();
+```
 
-- **Deletions:** Deletions via PATCH/PUT with empty arrays are not possible. Use the DELETE `/relationships/:name` endpoint if you need to remove specific attachments
+### Relationship Operations
 
-**Important:** `append_only: true` and `purge_on_nil: true` are mutually exclusive. If both are explicitly set, an `ArgumentError` will be raised at resource class definition time:
+**Update a relationship:**
 
-```ruby
-# This will raise ArgumentError
-has_many :documents, append_only: true, purge_on_nil: true
+```typescript
+await api
+  .one("user", "123")
+  .relationships("posts")
+  .patch([
+    { id: "1", type: "posts" },
+    { id: "2", type: "posts" },
+  ])
+  .toPromise();
 ```
 
-**Use cases for `append_only: true`:**
+### Authentication Middleware
 
-- When you want to accumulate attachments over time without replacing existing ones
-- When attachments represent a log or history that should only grow
-- When you need to prevent accidental replacement of existing attachments
-- When attachments should only be removed through explicit DELETE operations
+Add authentication middleware to automatically inject tokens:
 
-**Note:** `append_only` only applies to `has_many_attached` relationships. For `has_one_attached`, attachments are always replaced regardless of this setting.
+```typescript
+const authMiddleware = {
+  name: "auth",
+  req: (payload) => {
+    const token = localStorage.getItem("auth_token");
+    if (token) {
+      payload.req.headers = {
+        ...payload.req.headers,
+        Authorization: `Bearer ${token}`,
+      };
+    }
+    return payload;
+  },
+  error: (payload) => {
+    if (payload.res?.status === 401) {
+      localStorage.removeItem("auth_token");
+      // Redirect to login
+    }
+    throw payload;
+  },
+};
 
-Example usage in a controller:
+api.replaceMiddleware("add-bearer-token", authMiddleware);
+```
 
-```ruby
-def create
-  deserializer = JSONAPI::Deserializer.new(params, resource_class: User, action: :create)
-  attrs = deserializer.to_params
+### Polymorphic Relationships
 
-  # attrs will include:
-  # { "name" => "Jane Doe", "email" => "jane@example.com", "avatar" => <ActiveStorage::Blob>, "documents" => [<ActiveStorage::Blob>, ...] }
+For polymorphic relationships, omit the `type` in the model definition and provide it when creating/updating:
 
-  user = User.create!(attrs)
-  # Attachments are automatically attached via ActiveStorage
-end
+```typescript
+// Model definition - no type constraint
+api.define(
+  "workstream",
+  {
+    topic: {},
+    subject: {
+      jsonApi: "hasOne",
+      // No type - polymorphic
+    },
+  },
+  {
+    collectionPath: "workstreams",
+  }
+);
+
+// Create with polymorphic relationship
+const { data: workstream } = await api
+  .create("workstream", {
+    topic: "edit",
+    subject: { id: "456", type: "vendors" }, // Provide type at runtime
+  })
+  .toPromise();
 ```
 
 ### Error Handling
 
-Invalid signed IDs will raise `ActiveSupport::MessageVerifier::InvalidSignature`, which should be handled appropriately in your controllers.
+```typescript
+try {
+  const { data: user } = await api.find("user", "123").toPromise();
+} catch (error) {
+  if (error.response?.status === 401) {
+    // Authentication error
+  } else if (error.response?.status === 422) {
+    // Validation errors
+    const errors = error.response.data.errors;
+    errors.forEach((err) => {
+      console.error(`${err.source?.pointer}: ${err.detail}`);
+    });
+  } else if (error.response?.status === 400) {
+    // Bad request (invalid filters, sort fields, etc.)
+    console.error(error.response.data.errors);
+  }
+}
+```
 
-### Built-in ActiveStorage Resource
+### Key Integration Points
 
-The gem provides a built-in `JSONAPI::ActiveStorageBlobResource` that automatically serializes ActiveStorage blobs with:
+| Rails (json_api gem)           | devour-client-ts                                   |
+| ------------------------------ | -------------------------------------------------- |
+| `attributes :name, :email`     | `{ name: {}, email: {} }`                          |
+| `has_many :posts`              | `posts: { jsonApi: 'hasMany', type: 'posts' }`     |
+| `has_one :profile`             | `profile: { jsonApi: 'hasOne', type: 'profiles' }` |
+| `filters :name_eq`             | `filter: { name_eq: 'value' }`                     |
+| `sort=name,-date`              | `sort: ['name', '-date']`                          |
+| `include=posts.comments`       | `include: ['posts', 'posts.comments']`             |
+| `page[number]=1&page[size]=10` | `page: { number: 1, size: 10 }`                    |
+| `fields[users]=name,email`     | `fields: { users: ['name', 'email'] }`             |
 
-- `filename` - The original filename
-- `content_type` - MIME type
-- `byte_size` - File size in bytes
-- `checksum` - File checksum
-- Download link in the `links` section
+### Common Gotchas
 
-This resource is automatically used when serializing ActiveStorage attachments.
+1. **Plural types required**: All `type` values in relationships must be plural (`users`, not `user`)
+2. **Relationship assignment**: Assign relationships directly on the resource (`user: { id, type }`), not in a `relationships` wrapper
+3. **Content-Type header**: Must be `application/vnd.api+json` for POST/PATCH/PUT requests
+4. **Filter values**: Comma-separated filter values are parsed as a single string; use array notation for multiple values
 
 ## Contributing