If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JSONAPI-Resources/jsonapi-resources shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2mo ago
• 19 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JSONAPI-Resources/jsonapi-resources repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JSONAPI-Resources/jsonapi-resources.

What it runs against: a local clone of JSONAPI-Resources/jsonapi-resources — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JSONAPI-Resources/jsonapi-resources | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 96 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JSONAPI-Resources/jsonapi-resources. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JSONAPI-Resources/jsonapi-resources.git
#   cd jsonapi-resources
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JSONAPI-Resources/jsonapi-resources and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JSONAPI-Resources/jsonapi-resources(\\.git)?\\b" \\
  && ok "origin remote is JSONAPI-Resources/jsonapi-resources" \\
  || miss "origin remote is not JSONAPI-Resources/jsonapi-resources (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 96 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~66d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JSONAPI-Resources/jsonapi-resources"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

JSONAPI::Resources is a Rails library that automatically generates JSON:API-compliant REST API servers from resource definitions. It handles serialization, routing, filtering, sparse fieldsets, and pagination by convention, eliminating boilerplate controller and serializer code when building standards-compliant APIs. Modular Rails plugin architecture: lib/jsonapi/ contains core classes (Resource, ResourceController, Processor), lib/jsonapi/active_relation/ handles ORM integration with ActiveRecord adapters, lib/generators/jsonapi/ provides CLI scaffolding for Resources and Controllers, and lib/ root exposes the main entry point at lib/jsonapi-resources.rb.

Rails backend developers building JSON:API-compliant REST services who want to reduce repetitive serialization and controller logic. Specifically useful for teams adopting the JSON:API standard and wanting framework-level support rather than manual implementation.

Production-ready and stable. The library has a formal v0.10 alpha guide (implying versioning discipline), CI setup via GitHub Actions (.github/workflows/ruby.yml), comprehensive generator system, and active maintenance patterns. However, commit recency and star count are not visible in provided data; v0.10 is described as 'alpha' which may indicate slower release cadence.

Moderate risk: the v0.10 label as 'alpha' despite apparent maturity suggests possible breaking changes ahead. Single-maintainer pattern evident from Cerebris org structure. Dependency on Rails 5.1+ introduces version coupling risk. No visible test count or coverage metrics in the file list, making quality assessment difficult.

Unable to determine from provided file structure alone (no commit dates, PR list, or CHANGELOG visible). The presence of bug_report_templates/ for Rails 5 and master branches suggests ongoing compatibility maintenance, but specific active work items are not evident.

git clone https://github.com/cerebris/jsonapi-resources.git
cd jsonapi-resources
bundle install
rake test

Daily commands:

bundle install
rake test          # Run full test suite per README
# Or use individual Rails generators:
rails generate jsonapi:resource Post title:string
rails generate jsonapi:controller Posts

• lib/jsonapi/resource.rb: Core Resource class that all domain resources inherit from; defines attribute, relationship, and filter DSL
• lib/jsonapi/resource_controller.rb: Base controller class providing HTTP CRUD endpoints (GET, POST, PATCH, DELETE) with JSON:API compliance built-in
• lib/jsonapi/processor.rb: Request processing pipeline: parses JSON:API query string, validates, applies filters/includes/sparse fieldsets, coordinates serialization
• lib/jsonapi/resource_serializer.rb: Converts Resource instances into JSON:API document structure (data, relationships, included, links)
• lib/jsonapi/active_relation/join_manager.rb: Optimizes ActiveRecord queries by building efficient JOINs for included relationships, prevents N+1 queries
• lib/generators/jsonapi/resource_generator.rb: Scaffolding generator that creates boilerplate resource files matching ActiveRecord model schema
• lib/jsonapi/request.rb: Parses and validates incoming JSON:API requests (filters, includes, sparse fieldsets, pagination params)
• lib/jsonapi/error.rb: Structured error responses following JSON:API error object spec with status codes and detail messages

New Resource: Create via rails generate jsonapi:resource YourModel which scaffolds app/resources/your_model_resource.rb inheriting from JSONAPI::Resource. New Relationship: Edit the resource file and declare with has_one or has_many. Custom Serialization: Override attribute or relationship methods in the generated resource. Complex Queries: Modify lib/jsonapi/processor.rb or lib/jsonapi/active_relation/join_manager.rb for filtering logic.

Requires Rails 5.1+ — older Rails versions will fail silently or with cryptic errors. ActiveRecord-centric design: non-AR backends require implementing JSONAPI::BasicResource interface manually. include_directives parsing can fail silently if relationship names don't match resource definitions exactly. Sparse fieldsets and include directives must be precompiled by the Processor before serialization — raw requests bypass this. No obvious env var requirements, but database must be configured for ActiveRecord adapters to function.

• JSON:API Specification Compliance — JR's entire purpose is guaranteeing your API conforms to the JSON:API spec; understanding the spec's document structure, error format, and query string conventions is essential to using JR effectively
• Resource-Centric API Design (vs. Controller-Centric) — JR inverts typical Rails design by organizing around resources (domain entities) rather than HTTP endpoints; this shapes how you define attributes, relationships, and permissions
• Sparse Fieldsets — JR implements JSON:API's sparse fieldset syntax (?fields[posts]=title,body) to allow clients to request only needed attributes, reducing response size; misunderstanding this can break client expectations
• Compound Documents (Included Resources) — JR's include_directives.rb handles the ?include=author,comments query syntax to embed related resources in a single response, preventing N+1 queries when done correctly via join_manager.rb
• Query String Filtering & Sorting — JR's filter system (lib/jsonapi/resource.rb filter DSL) translates ?filter[status]=active&sort=-created_at into ActiveRecord scopes; implementing filters requires understanding both JSON:API conventions and Rails query patterns
• Pagination with Cursor/Offset — JR's paginator.rb handles both offset-based (?page[offset]=10&page[limit]=20) and cursor-based pagination; the choice impacts query performance and client state management
• Authorization Callbacks (filters in Resources) — JR provides after_create, before_update callback hooks in resources for permission checks; misplacing authorization logic (controller vs. resource) can lead to security gaps

• rails-api/rails-api — Predecessor project that inspired API-focused Rails patterns; now merged into Rails core but contextually relevant to understanding JR's design philosophy
• cerebris/peeps — Official demo app referenced in README showcasing how to use jsonapi-resources in a complete Rails application
• Netflix/fast_jsonapi — Alternative JSON serializer for Rails with JSON:API support; simpler and faster but less opinionated than JR's resource-centric approach
• jsonapi/jsonapi-resources-demo — Community demo repo that extends jsonapi-resources with additional patterns and best practices
• json-api/json-api — Official JSON:API specification repository; essential reference for understanding the compliance target and edge cases

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for lib/jsonapi/active_relation/join_manager.rb

The join_manager.rb is a critical component for handling complex relationship joins in ActiveRecord queries, but there's no dedicated test file visible in the test directory. This core query-building logic needs robust test coverage to prevent regressions when handling edge cases like nested includes, circular references, and multiple join types.

• [ ] Create test/active_relation/join_manager_test.rb with fixtures for various relationship types
• [ ] Add tests for single and nested join scenarios using the existing test fixtures (answers.yml, access_cards.yml, etc.)
• [ ] Add tests for edge cases: circular relationship includes, self-referential relationships, and polymorphic joins
• [ ] Ensure tests cover both left join adapter behavior in lib/jsonapi/active_relation/adapters/join_left_active_record_adapter.rb

Add GitHub Actions workflow to test against multiple Rails versions

The repo has bug_report_templates for Rails 5 (rails_5_latest.rb and rails_5_master.rb) but the CI workflow in .github/workflows/ruby.yml doesn't show explicit Rails version matrix testing. The project needs to verify compatibility across Rails 5.x and 6.x versions to catch breaking changes early.

• [ ] Extend .github/workflows/ruby.yml to add a matrix strategy testing against Rails 5.2, 6.0, 6.1, and 7.0
• [ ] Verify gemspec constraints in jsonapi-resources.gemspec match the tested versions
• [ ] Add separate test jobs for ActiveRecord adapter tests given lib/jsonapi/active_relation/ complexity
• [ ] Document supported Rails versions in README.md based on the matrix results

Add integration tests for lib/jsonapi/resource_controller.rb and lib/jsonapi/acts_as_resource_controller.rb

While controller_test.rb exists, there's no clear integration test coverage for the full request/response cycle of resource_controller.rb with acts_as_resource_controller.rb. These modules are the HTTP entry point and need tests validating error handling, response formatting, and relationship updates in realistic scenarios.

• [ ] Create test/integration/resource_controller_integration_test.rb with realistic request scenarios
• [ ] Test full CRUD operations with proper JSON:API response validation using lib/jsonapi/response_document.rb
• [ ] Add tests for error scenarios (validation failures, permission denials) that exercise lib/jsonapi/error.rb and error_codes.rb
• [ ] Include tests for relationship updates and sparse fieldsets to validate lib/jsonapi/include_directives.rb parsing

• Add test coverage for lib/jsonapi/cached_response_fragment.rb — file exists but appears untested based on sparse test references in file list; implement caching layer tests.
• Document the lib/jsonapi/operation.rb and lib/jsonapi/operation_result.rb pair — these handle bulk operations but lack usage examples in provided docs; add a bulk-create guide to the v0.10 guide.
• Extend lib/generators/jsonapi/templates/jsonapi_resource.rb to auto-generate filter definitions based on ActiveRecord column types (e.g., filter :created_at, apply: ->(records, value, _options) { records.where('created_at > ?', value) }) reducing boilerplate.

The JSONAPI::Resources library shows a resource-focused Rails architecture with moderate security concerns. The primary issues are: (1) inability to verify dependency security without the actual Gemfile contents, (2) potential SQL injection risks in the ActiveRel

• High · Missing Dependency File Analysis — Gemfile, jsonapi-resources.gemspec. The Gemfile and gemspec files are referenced but their contents were not provided for analysis. This prevents verification of known vulnerable gem versions and outdated dependencies. Fix: Provide complete dependency files and run 'bundle audit' or 'bundler-audit' to check for known vulnerabilities in gems. Regularly update dependencies and monitor security advisories.
• Medium · Potential SQL Injection Risk in ActiveRelation Adapter — lib/jsonapi/active_relation/adapters/join_left_active_record_adapter.rb. The file 'lib/jsonapi/active_relation/adapters/join_left_active_record_adapter.rb' suggests custom SQL query building for joins. Without reviewing the actual code, there's a risk of SQL injection if user input is not properly parameterized. Fix: Review all SQL query construction code to ensure parameterized queries are used. Never concatenate user input directly into SQL. Use ActiveRecord's built-in methods for query construction.
• Medium · Potential XSS Risk in Resource Serialization — lib/jsonapi/resource_serializer.rb, lib/jsonapi/compiled_json.rb. The resource serializer ('lib/jsonapi/resource_serializer.rb') handles JSON output without visible HTML escaping mechanisms. If user-supplied data is serialized without proper encoding, XSS vulnerabilities could occur. Fix: Ensure all user-supplied attributes are properly escaped/encoded before JSON serialization. Use Rails built-in JSON encoding which handles escaping by default. Validate and sanitize input data.
• Medium · Authorization/Access Control Not Visible — lib/jsonapi/resource_controller.rb, lib/jsonapi/acts_as_resource_controller.rb. The codebase appears to handle resource-based access, but without seeing the actual implementation of authorization checks in 'lib/jsonapi/resource_controller.rb' and 'lib/jsonapi/acts_as_resource_controller.rb', it's unclear if proper authorization is enforced on all operations. Fix: Implement and enforce comprehensive authorization checks for all CRUD operations. Use a well-tested authorization library like Pundit or CanCanCan. Ensure authorization is checked before data access.
• Medium · Potential Mass Assignment Vulnerabilities — lib/generators/jsonapi/templates/jsonapi_resource.rb, lib/jsonapi/resource.rb. Resource definitions in templates and generators may not properly restrict which attributes can be mass-assigned, potentially allowing unauthorized attribute modification. Fix: Implement strict attribute whitelisting. Only allow intentionally designed attributes to be writable. Use Rails' strong_parameters or equivalent filtering for all user inputs.
• Low · No Visible CSRF Protection Configuration — lib/jsonapi/resource_controller_metal.rb. While Rails includes CSRF protection by default, the JSON:API specific controller implementation should be verified to ensure CSRF tokens are properly validated for state-changing operations. Fix: Verify that CSRF protection is properly configured in the base resource controller. Ensure all POST, PATCH, DELETE requests require valid CSRF tokens.
• Low · Insufficient Input Validation Visibility — lib/jsonapi/resource.rb, lib/jsonapi/basic_resource.rb. No obvious input validation framework visible in the file structure. Validation logic may be scattered or missing. Fix: Implement comprehensive input validation for all resource attributes. Use Rails validators or a dedicated validation library. Validate data types, lengths, formats, and allowed values.
• Low · No Visible Rate Limiting Implementation — lib/jsonapi/resource_controller.rb. No rate limiting or throttling mechanisms are apparent in the file structure, making the API potentially vulnerable to abuse and DoS attacks. Fix: Implement rate limiting using gems like 'rack-attack' or 'rack-throttle'. Configure appropriate limits for different endpoints and users to prevent abuse.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.