jpie 0.1.0

data/README.md

@@ -0,0 +1,2159 @@
+# JSONAPI
+
+A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API controllers for producing and consuming JSON:API resources.
+
+## Features
+
+- JSON:API v1.1 compliant routing and controllers
+- Automatic MIME type registration (`application/vnd.api+json`)
+- Generic resource controller with CRUD operations
+- Built-in serialization and deserialization
+- Support for filtering (explicit filters with column-aware operators), sorting, pagination, sparse fieldsets, and includes
+- Relationship endpoints for managing resource relationships independently
+- Separate creatable and updatable field definitions
+- Configurable pagination options
+- Content negotiation with Accept and Content-Type headers
+- Support for polymorphic and STI relationships
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json_api'
+```
+
+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
+
+Use the `jsonapi_resources` DSL in your routes file:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  jsonapi_resources :users
+  jsonapi_resources :posts
+end
+```
+
+This creates standard RESTful routes (index, show, create, update, destroy) that default to the `json_api/resources` controller and `jsonapi` format.
+
+**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.
+
+### Resource Definitions
+
+Define resource classes to control which attributes and relationships are exposed via the JSON:API endpoint:
+
+```ruby
+# app/resources/user_resource.rb
+class UserResource < JSONAPI::Resource
+  attributes :email, :name, :phone
+
+  has_many :posts
+  has_one :profile
+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
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :full_name
+
+  # Virtual attribute getter
+  def full_name
+    "#{resource.name} (#{resource.email})"
+  end
+end
+```
+
+The getter method receives the underlying model instance via `resource`. Virtual attributes are serialized just like regular attributes and appear in the response:
+
+```json
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com",
+      "full_name": "John Doe (john@example.com)"
+    }
+  }
+}
+```
+
+#### 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:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :display_name
+  creatable_fields :name, :email, :display_name
+  updatable_fields :name, :display_name
+
+  def initialize(resource = nil, context = {})
+    super
+    @transformed_params = {}
+  end
+
+  # Setter that transforms virtual attribute to model attribute
+  def display_name=(value)
+    @transformed_params["name"] = value.upcase
+  end
+
+  # Getter for the virtual attribute (for serialization)
+  def display_name
+    resource&.name&.downcase
+  end
+
+  # Return transformed params accumulated by setters
+  def transformed_params
+    @transformed_params || {}
+  end
+end
+```
+
+When a client sends `display_name` in a create or update request, the setter transforms it to `name` (uppercase). The virtual attribute `display_name` is automatically excluded from the final params returned by the deserializer, so it won't be passed to the model.
+
+**Important**: You must initialize `@transformed_params` in your `initialize` method if you use setters that modify it.
+
+### Custom Controllers
+
+If you need custom behavior, you can override the default controller:
+
+```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):**
+
+```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"
+    }
+  }
+}
+```
+
+**DELETE /users/:id:**
+
+Returns `204 No Content` with an empty response body.
+
+### Query Parameters
+
+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
+
+#### Filtering
+
+Filtering requires declaring permitted filters in your resource class:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :phone
+  filters :name_eq, :name_match, :created_at_gte
+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:
+
+**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
+```
+
+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)
+
+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
+```
+
+- 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.
+
+#### Pagination
+
+Resources can be paginated using the `page[number]` and `page[size]` parameters. Pagination is only available on collection (index) endpoints.
+
+Examples:
+
+- `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)
+
+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.
+
+**Example Paginated Response:**
+
+```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"
+      }
+    }
+  ],
+  "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"
+  },
+  "meta": {
+    "total": 15
+  }
+}
+```
+
+#### Including Related Resources
+
+Use the `include` parameter to include related resources in the response. This is available on both index and show endpoints:
+
+```ruby
+# Include single relationship
+GET /users?include=posts
+
+# Include multiple relationships
+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:
+
+```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
+        }
+      }
+    },
+    "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"
+      }
+    }
+  ]
+}
+```
+
+#### Polymorphic Relationships
+
+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:
+
+```ruby
+# User belongs_to :profile, polymorphic: true
+# User has_many :activities, as: :actor
+
+GET /users?include=profile
+GET /users?include=activities
+GET /users/:id?include=profile,activities
+```
+
+The response will include the correct resource type for each polymorphic association (e.g., `customer_profiles` or `admin_profiles` for a polymorphic `profile` association).
+
+**Example Response with Polymorphic Relationship:**
+
+```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"
+        }
+      }
+    },
+    "links": {
+      "self": "/users/1"
+    }
+  },
+  "included": [
+    {
+      "type": "admin_profiles",
+      "id": "1",
+      "attributes": {
+        "department": "Engineering",
+        "level": "Senior"
+      },
+      "links": {
+        "self": "/admin_profiles/1"
+      }
+    }
+  ]
+}
+```
+
+#### Single Table Inheritance (STI) Support
+
+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.
+
+##### Routing
+
+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:
+
+```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
+```
+
+##### Resource Definitions
+
+Define a resource class for the base model and each subclass. Subclasses should inherit from the base resource class to share configuration:
+
+```ruby
+# app/resources/notification_resource.rb
+class NotificationResource < JSONAPI::Resource
+  attributes :body, :created_at
+  has_one :user
+end
+
+# app/resources/email_notification_resource.rb
+class EmailNotificationResource < NotificationResource
+  attributes :subject, :recipient_email
+end
+
+# app/resources/sms_notification_resource.rb
+class SmsNotificationResource < NotificationResource
+  attributes :phone_number
+end
+```
+
+##### Serialization
+
+Resources are serialized with their specific type. When querying the base endpoint (e.g., `GET /notifications`), the response will contain a mix of types:
+
+```json
+{
+  "data": [
+    {
+      "type": "email_notifications",
+      "id": "1",
+      "attributes": {
+        "body": "Welcome!",
+        "subject": "Hello"
+      }
+    },
+    {
+      "type": "sms_notifications",
+      "id": "2",
+      "attributes": {
+        "body": "Code: 1234",
+        "phone_number": "555-1234"
+      }
+    }
+  ]
+}
+```
+
+##### Creating STI Resources
+
+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
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "email_notifications",
+    "attributes": {
+      "subject": "Important",
+      "body": "Please read this.",
+      "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
+
+The gem supports sorting by virtual attributes (attributes that don't correspond to database columns). When sorting by a virtual attribute, the gem:
+
+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
+```
+
+**Example:**
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :full_name
+
+  def full_name
+    "#{resource.name} (#{resource.email})"
+  end
+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
+
+All responses automatically include a `jsonapi` object indicating JSON:API version compliance:
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": { ... }
+}
+```
+
+You can customize 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
+
+The gem supports meta information at three levels: document-level, resource-level, and relationship-level.
+
+#### Document-Level Meta
+
+Document-level meta appears at the top level of the response and is typically used for pagination:
+
+```json
+{
+  "jsonapi": { "version": "1.1" },
+  "data": [ ... ],
+  "meta": {
+    "total": 100
+  }
+}
+```
+
+Pagination automatically includes meta with the total count when pagination is applied.
+
+**Example Document-Level Meta:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": [
+    {
+      "type": "users",
+      "id": "1",
+      "attributes": {
+        "name": "John Doe",
+        "email": "john@example.com"
+      }
+    }
+  ],
+  "meta": {
+    "total": 100
+  }
+}
+```
+
+#### 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.
+
+You can also define custom meta in two ways:
+
+**Class-level static meta:**
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :email, :name
+
+  meta({ version: "v1", custom: "value" })
+end
+```
+
+**Instance-level dynamic meta:**
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :email, :name
+
+  def meta
+    {
+      name_length: resource.name.length,
+      custom_field: "value"
+    }
+  end
+end
+```
+
+The instance method has access to the model instance via `resource`. Custom meta is merged with the default timestamp meta, with custom values taking precedence.
+
+**Example Resource-Level Meta:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "meta": {
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-15T10:30:00Z",
+      "name_length": 8,
+      "custom_field": "value"
+    },
+    "links": {
+      "self": "/users/1"
+    }
+  }
+}
+```
+
+#### Relationship-Level Meta
+
+Relationship-level meta appears within relationship objects:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :email, :name
+
+  has_many :posts, meta: { count: 5, custom: "relationship_meta" }
+  has_one :profile, meta: { type: "polymorphic" }
+end
+```
+
+The response will include:
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "relationships": {
+      "posts": {
+        "data": [
+          { "type": "posts", "id": "1" },
+          { "type": "posts", "id": "2" }
+        ],
+        "meta": {
+          "count": 5,
+          "custom": "relationship_meta"
+        }
+      },
+      "profile": {
+        "data": {
+          "type": "admin_profiles",
+          "id": "1"
+        },
+        "meta": {
+          "type": "polymorphic"
+        }
+      }
+    },
+    "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
+
+  def update?
+    user.admin? || user == record
+  end
+
+  def destroy?
+    user.admin?
+  end
+
+  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
+end
+```
+
+#### Relationship Authorization
+
+Relationship endpoints (show, update, destroy) authorize the parent resource using the `:update` action with a context hash containing the relationship name:
+
+```ruby
+# The authorization_handler receives:
+{
+  controller: controller_instance,
+  record: parent_resource,
+  action: :update,
+  context: { relationship: :posts }
+}
+```
+
+This allows you to implement relationship-specific authorization logic in your policies if needed.
+
+#### Custom Authorization Error Handling
+
+The gem automatically handles `JSONAPI::AuthorizationError` and `Pundit::NotAuthorizedError` exceptions, rendering a JSON:API compliant `403 Forbidden` response:
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "403",
+      "title": "Forbidden",
+      "detail": "You are not authorized to perform this action"
+    }
+  ]
+}
+```
+
+You can customize the error message by raising an exception with a specific message:
+
+```ruby
+raise JSONAPI::AuthorizationError, "Not authorized to view this resource"
+```
+
+#### Overriding Authorization
+
+Authorization hooks can be easily overridden or disabled:
+
+```ruby
+# Disable authorization (allow all access)
+JSONAPI.configure do |config|
+  config.authorization_scope = nil
+  config.authorization_handler = nil
+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"
+    end
+  end
+end
+```
+
+### 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
+
+The gem emits events for resource lifecycle operations:
+
+- **`jsonapi.{resource_type}.created`** - Emitted after successful resource creation
+- **`jsonapi.{resource_type}.updated`** - Emitted after successful resource updates (includes changed fields)
+- **`jsonapi.{resource_type}.deleted`** - Emitted after successful resource deletion
+
+**Event Payload Structure:**
+
+```ruby
+{
+  resource_type: "users",
+  resource_id: 123,
+  changes: { "name" => ["old", "new"], "phone" => ["old", "new"] }  # Only for updates
+}
+```
+
+**Example Usage:**
+
+```ruby
+# Subscribe to events
+class JsonApiEventSubscriber
+  def emit(event)
+    encoded = ActiveSupport::EventReporter.encoder(:json).encode(event)
+    # Forward to your monitoring service
+    MonitoringService.send_event(encoded)
+  end
+end
+
+Rails.event.subscribe(JsonApiEventSubscriber.new) if Rails.respond_to?(:event)
+```
+
+#### Relationship Events
+
+The gem also emits events for relationship operations:
+
+- **`jsonapi.{resource_type}.relationship.updated`** - Emitted after successful relationship updates
+- **`jsonapi.{resource_type}.relationship.removed`** - Emitted after successful relationship removals
+
+**Event Payload Structure:**
+
+```ruby
+{
+  resource_type: "users",
+  resource_id: 123,
+  relationship_name: "posts",
+  related_type: "posts",      # Optional
+  related_ids: [456, 789]      # Optional
+}
+```
+
+#### Testing Instrumentation
+
+Use Rails 8.1's `assert_events_reported` test helper to verify events are emitted:
+
+```ruby
+assert_events_reported([
+  { name: "jsonapi.users.created", payload: { resource_type: "users", resource_id: 123 } },
+  { name: "jsonapi.users.relationship.updated", payload: { relationship_name: "posts" } }
+]) do
+  post "/users", params: payload.to_json, headers: jsonapi_headers
+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
+
+The gem enforces JSON:API content negotiation:
+
+- **Content-Type**: POST, PATCH, and PUT requests must include `Content-Type: application/vnd.api+json` header (returns `415 Unsupported Media Type` if missing)
+- **Accept**: If an `Accept` header is provided, it must include `application/vnd.api+json` or be `*/*` (returns `406 Not Acceptable` if explicitly set to non-JSON:API types)
+
+Blank or `*/*` Accept headers are allowed to support browser defaults.
+
+### Custom Controllers
+
+You can inherit from `JSONAPI::BaseController` to create custom controllers:
+
+```ruby
+class UsersController < JsonApi::BaseController
+  def index
+    # Custom implementation
+  end
+end
+```
+
+The base controller provides helper methods:
+
+- `jsonapi_params` - Parsed JSON:API parameters
+- `jsonapi_attributes` - Extracted attributes
+- `jsonapi_relationships` - Extracted relationships
+- `parse_include_param` - Parsed include parameter
+- `parse_fields_param` - Parsed fields parameter
+- `parse_filter_param` - Parsed filter parameter
+- `parse_sort_param` - Parsed sort parameter
+- `parse_page_param` - Parsed page parameter
+
+### Serialization
+
+Use `JSONAPI::Serializer` to serialize resources:
+
+```ruby
+serializer = JSONAPI::Serializer.new(user)
+serializer.to_hash(include: ["posts"], fields: { users: ["name", "email"] })
+```
+
+### Deserialization
+
+Use `JSONAPI::Deserializer` to deserialize JSON:API payloads:
+
+```ruby
+deserializer = JSONAPI::Deserializer.new(params, resource_class: User)
+deserializer.attributes # => { "name" => "John", "email" => "john@example.com" }
+deserializer.relationship_ids(:posts) # => ["1", "2"]
+deserializer.to_params # => { "name" => "John", "post_ids" => ["1", "2"], "profile_id" => "1", "profile_type" => "CustomerProfile" }
+```
+
+The deserializer automatically converts JSON:API relationship format to Rails-friendly params:
+
+- To-many relationships: `posts` → `post_ids` (array)
+- To-one relationships: `account` → `account_id`
+- Polymorphic relationships: `profile` → `profile_id` and `profile_type`
+
+#### Creating Resources with Relationships
+
+You can include relationships when creating resources:
+
+```ruby
+# POST /users
+{
+  "data": {
+    "type": "users",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "relationships": {
+      "profile": {
+        "data": {
+          "type": "customer_profiles",
+          "id": "1"
+        }
+      },
+      "posts": {
+        "data": [
+          { "type": "posts", "id": "1" },
+          { "type": "posts", "id": "2" }
+        ]
+      }
+    }
+  }
+}
+```
+
+#### Updating Resources with Relationships
+
+You can update relationships when updating resources:
+
+```ruby
+# PATCH /users/:id
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe Updated"
+    },
+    "relationships": {
+      "profile": {
+        "data": {
+          "type": "admin_profiles",
+          "id": "2"
+        }
+      },
+      "posts": {
+        "data": [
+          { "type": "posts", "id": "3" }
+        ]
+      }
+    }
+  }
+}
+```
+
+#### 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
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "profile": {
+        "data": null
+      }
+    }
+  }
+}
+
+# Clear to-many relationship
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "posts": {
+        "data": []
+      }
+    }
+  }
+}
+```
+
+#### Relationship Validation
+
+The gem validates relationship data:
+
+- Missing `type` or `id` in relationship data returns `400 Bad Request`
+- Invalid relationship type (for non-polymorphic associations) returns `400 Bad Request`
+- 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
+
+The gem provides dedicated endpoints for managing relationships independently of the main resource:
+
+#### Show Relationship
+
+```ruby
+GET /users/:id/relationships/posts
+```
+
+Returns the relationship data (resource identifiers) with links and meta:
+
+**To-Many Relationship Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": [
+    { "type": "posts", "id": "1" },
+    { "type": "posts", "id": "2" }
+  ],
+  "links": {
+    "self": "/users/1/relationships/posts",
+    "related": "/users/1/posts"
+  },
+  "meta": {
+    "count": 2
+  }
+}
+```
+
+**To-One Relationship Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": {
+    "type": "admin_profiles",
+    "id": "1"
+  },
+  "links": {
+    "self": "/users/1/relationships/profile",
+    "related": "/users/1/profile"
+  }
+}
+```
+
+**Empty To-One Relationship Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": null,
+  "links": {
+    "self": "/users/1/relationships/profile",
+    "related": "/users/1/profile"
+  }
+}
+```
+
+For collection relationships, you can sort using the `sort` parameter:
+
+```ruby
+GET /users/:id/relationships/posts?sort=title,-created_at
+```
+
+#### Update Relationship
+
+```ruby
+PATCH /users/:id/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "3" },
+    { "type": "posts", "id": "4" }
+  ]
+}
+```
+
+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
+
+```ruby
+DELETE /users/:id/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "1" }
+  ]
+}
+```
+
+Removes specific resources from a to-many relationship by setting their foreign key to `NULL`. For to-one relationships, send a single resource identifier object to remove the linkage.
+
+**Important**: Per JSON:API specification, relationship endpoints (`DELETE /users/:id/relationships/posts`) only modify linkage and never destroy resources. The gem attempts to unset the linkage by setting the foreign key to `NULL`. If this operation fails (due to NOT NULL constraints, validations, or other database constraints), a `400 Bad Request` error is returned. To allow relationship removal, ensure the foreign key column allows `NULL` values and any validations permit nullification.
+
+Error responses follow JSON:API error format:
+
+**Example Error Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "400",
+      "title": "Invalid Relationship",
+      "detail": "Invalid relationship type for profile: 'invalid_type' does not correspond to a valid model class",
+      "source": {
+        "pointer": "/data/relationships/profile/data/type"
+      }
+    }
+  ]
+}
+```
+
+**Example 404 Not Found Error:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "404",
+      "title": "Record Not Found",
+      "detail": "Couldn't find User with 'id'=999"
+    }
+  ]
+}
+```
+
+**Example Validation Error:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "422",
+      "title": "Validation Error",
+      "detail": "Email can't be blank",
+      "source": {
+        "pointer": "/data/attributes/email"
+      }
+    },
+    {
+      "status": "422",
+      "title": "Validation Error",
+      "detail": "Name is too short (minimum is 2 characters)",
+      "source": {
+        "pointer": "/data/attributes/name"
+      }
+    }
+  ]
+}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Code Organization
+
+The gem is organized into several directories within `lib/json_api/`:
+
+- **`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
+
+This organization makes it easier to understand the gem's structure and locate specific functionality.
+
+## Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+### Test Helper for Request Specs
+
+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.
+
+**Setup (RSpec):**
+
+```ruby
+# spec/rails_helper.rb or spec/support/json_api.rb
+require "json_api/testing"
+
+RSpec.configure do |config|
+  config.include JSONAPI::Testing::TestHelper, type: :request
+end
+```
+
+**Usage:**
+
+```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
+
+  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
+```
+
+**Behavior by HTTP method:**
+
+| 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       |
+
+### Integration Tests
+
+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.
+
+To run only integration tests:
+
+```bash
+bundle exec rspec spec/integration
+```
+
+The integration tests cover:
+
+- 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
+
+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.
+
+## ActiveStorage Support
+
+The gem includes built-in support for serializing and deserializing ActiveStorage attachments through JSON:API.
+
+### Serializing Attachments
+
+When a model has ActiveStorage attachments (`has_one_attached` or `has_many_attached`), you can expose them as relationships in your resource:
+
+```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
+```
+
+The serializer will automatically:
+
+- 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)
+
+Example response:
+
+```json
+{
+  "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" }
+        ]
+      }
+    },
+    "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"
+      }
+    }
+  ]
+}
+```
+
+### Deserializing Attachments
+
+When creating or updating resources, clients can attach files by providing signed blob IDs obtained from ActiveStorage direct uploads:
+
+```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" }
+        ]
+      }
+    }
+  }
+}
+```
+
+The deserializer will:
+
+- 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]`)
+
+#### Detaching Attachments
+
+To detach (remove) an attachment, send `null` for to-one relationships or an empty array `[]` for to-many relationships:
+
+```json
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "avatar": {
+        "data": null
+      },
+      "documents": {
+        "data": []
+      }
+    }
+  }
+}
+```
+
+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.
+
+#### Controlling Purge Behavior with `purge_on_nil`
+
+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:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+
+  # Opt out of purging when set to nil
+  has_one :avatar, purge_on_nil: false
+  has_many :documents, purge_on_nil: false
+end
+```
+
+When `purge_on_nil: false` is set:
+
+- 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`)
+
+**Use cases for `purge_on_nil: false`:**
+
+- 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
+
+**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.
+
+#### Append-Only Mode with `append_only`
+
+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:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+
+  # Enable append-only mode for documents
+  has_many :documents, append_only: true
+end
+```
+
+**Behavior when `append_only: true` is set:**
+
+- **Appending new blobs:** When updating a resource with new blobs in the relationship, they are added to the existing attachments instead of replacing them
+
+  ```json
+  // Existing attachments: [blob1, blob2]
+  // Payload includes: [blob3, blob4]
+  // Result: [blob1, blob2, blob3, blob4]
+  ```
+
+- **Empty array is a no-op:** Sending an empty array `[]` preserves all existing attachments
+
+  ```json
+  // Existing attachments: [blob1, blob2]
+  // Payload includes: []
+  // Result: [blob1, blob2] (unchanged)
+  ```
+
+- **Implicit `purge_on_nil: false`:** When `append_only: true` is set, `purge_on_nil` is automatically set to `false` and cannot be overridden
+
+- **Deletions:** Deletions via PATCH/PUT with empty arrays are not possible. Use the DELETE `/relationships/:name` endpoint if you need to remove specific attachments
+
+**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:
+
+```ruby
+# This will raise ArgumentError
+has_many :documents, append_only: true, purge_on_nil: true
+```
+
+**Use cases for `append_only: true`:**
+
+- 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
+
+**Note:** `append_only` only applies to `has_many_attached` relationships. For `has_one_attached`, attachments are always replaced regardless of this setting.
+
+Example usage in a controller:
+
+```ruby
+def create
+  deserializer = JSONAPI::Deserializer.new(params, resource_class: User, action: :create)
+  attrs = deserializer.to_params
+
+  # attrs will include:
+  # { "name" => "Jane Doe", "email" => "jane@example.com", "avatar" => <ActiveStorage::Blob>, "documents" => [<ActiveStorage::Blob>, ...] }
+
+  user = User.create!(attrs)
+  # Attachments are automatically attached via ActiveStorage
+end
+```
+
+### Error Handling
+
+Invalid signed IDs will raise `ActiveSupport::MessageVerifier::InvalidSignature`, which should be handled appropriately in your controllers.
+
+### Built-in ActiveStorage Resource
+
+The gem provides a built-in `JSONAPI::ActiveStorageBlobResource` that automatically serializes ActiveStorage blobs with:
+
+- `filename` - The original filename
+- `content_type` - MIME type
+- `byte_size` - File size in bytes
+- `checksum` - File checksum
+- Download link in the `links` section
+
+This resource is automatically used when serializing ActiveStorage attachments.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/klaay/json_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).