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/Netflix/fast_jsonapi 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 all four use cases

• 25+ active contributors
• Distributed ownership (top contributor 25% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago

_{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 Netflix/fast_jsonapi repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Netflix/fast_jsonapi.

What it runs against: a local clone of Netflix/fast_jsonapi — 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 Netflix/fast_jsonapi | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 1190 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Netflix/fast_jsonapi. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Netflix/fast_jsonapi.git
#   cd fast_jsonapi
#
# 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 Netflix/fast_jsonapi and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 1190 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1160d)"
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/Netflix/fast_jsonapi"
  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).

fast_jsonapi is a high-performance JSON:API serializer for Ruby objects that converts domain models into spec-compliant JSON:API responses 25-46x faster than Active Model Serializers. It generates properly formatted compound documents with included relationships, sparse fieldsets, and caching support while maintaining a declarative, Rails-friendly DSL. Traditional gem structure: lib/fast_jsonapi/ contains the core ObjectSerializer mixin (lib/fast_jsonapi/object_serializer.rb), relationship/attribute builders (lib/fast_jsonapi/relationship.rb, lib/fast_jsonapi/attribute.rb), instrumentation hooks for Skylight (lib/fast_jsonapi/instrumentation/skylight/), and a Rails generator (lib/generators/serializer/). spec/ mirrors lib/ structure with comprehensive test coverage for each component.

Ruby/Rails developers building JSON APIs who need to serialize large datasets (100s-1000s of records) with complex relationships while maintaining strict performance budgets. Particularly valuable for teams using Netflix's original architecture that prioritize serialization speed over flexibility.

⚠️ Archived/No longer maintained — the project shows solid production quality (137k lines of Ruby, comprehensive RSpec tests in spec/, Travis CI configured in .travis.yml, structured lib/ with clear separation of concerns) but Netflix explicitly states in the README this is unmaintained and recommends the fork jsonapi-serializer/jsonapi-serializer instead. Suitable only for existing codebases; new projects should use the maintained fork.

High maintenance risk: Project is explicitly abandoned by Netflix with no recent commits, no active issue triage, and potential dependency drift (Gemfile dependencies not visible but likely outdated given age). Single-maintainer project with no apparent succession plan. The JSON:API spec may have evolved since last update. Use only if committed to forking or adopting the maintained fork (jsonapi-serializer/jsonapi-serializer).

Nothing — project is archived. No active development, no open PRs being merged, no milestones. The README explicitly states 'No Longer Maintained' and directs users to the jsonapi-serializer fork. Last known activity is old Travis CI configuration (.travis.yml) and version frozen at lib/fast_jsonapi/version.rb.

git clone https://github.com/Netflix/fast_jsonapi.git
cd fast_jsonapi
bundle install
bundle exec rspec

(Note: This is for inspection/forking only; use jsonapi-serializer/jsonapi-serializer gem for new projects)

Daily commands: This is a library gem, not an executable. To run tests: bundle exec rspec. To use in a Rails project: add gem 'fast_jsonapi' to Gemfile, then rails g serializer ModelName field1 field2 to generate a serializer. See docs/object_serializer.json and docs/collection_serializer_output.json for expected output format.

• lib/fast_jsonapi/object_serializer.rb: Core module that users include in their serializers; defines set_type, attributes, has_many/belongs_to/has_one DSL and orchestrates serialization
• lib/fast_jsonapi/serialization_core.rb: Contains the actual serialization algorithm (to_hash, serialize_hash) that builds the JSON:API response structure; performance-critical path
• lib/fast_jsonapi/relationship.rb: Handles belongs_to, has_many, and has_one relationship declarations and their serialization into JSON:API included/relationship sections
• spec/lib/object_serializer_caching_spec.rb: Tests caching behavior (set_cache_length_expires_in) which is a key performance feature distinguishing this from competitors
• lib/generators/serializer/serializer_generator.rb: Rails generator that scaffolds new serializer classes; entry point for Rails developers new to the gem
• lib/fast_jsonapi/instrumentation/skylight/: Optional performance monitoring integration showing how serializer can be instrumented; useful for understanding bottleneck analysis patterns

Core serialization logic: lib/fast_jsonapi/serialization_core.rb (main render/to_hash methods). Relationships: lib/fast_jsonapi/relationship.rb for belongs_to/has_many/has_one handling. Attributes: lib/fast_jsonapi/attribute.rb for conditional/dynamic attribute rendering. Tests: Add specs to spec/lib/object_serializer_*.rb following existing patterns. Generator: lib/generators/serializer/templates/serializer.rb.tt for Rails scaffold template.

No longer maintained — the biggest trap is assuming this will receive security updates or bug fixes. JSON:API version drift: gem was built for JSON:API spec version current at time of abandonment; newer spec clarifications may not be reflected. Relationship N+1 queries: Gem handles serialization speed but does NOT auto-prevent N+1 queries on belongs_to/has_many relationships; you must eager-load associations yourself (use includes in your ActiveRecord queries). No runtime dependency list visible: Gemfile not shown; transitive dependency vulns may exist. Rails version constraints unclear: .travis.yml visible but specific Ruby/Rails version targets not fully documented in provided snippet.

• JSON:API Specification Compliance — This gem's entire purpose is generating JSON:API-spec-compliant responses; understanding the spec's requirements for structure, relationships, compound documents, and sparse fieldsets is essential to using this library correctly
• Compound Documents (Included Resources) — fast_jsonapi optimizes serialization of related objects in a single response (the 'included' section of JSON:API); this is a performance-critical feature that distinguishes it from simpler serializers and requires understanding N+1 prevention
• Sparse Fieldsets (Partial Serialization) — JSON:API clients can request only specific attributes/relationships via query params; this gem implements this optimization where only requested fields are serialized, reducing payload size and CPU work
• Instrumentation Hooks & APM Integration — The gem includes optional Skylight instrumentation (lib/fast_jsonapi/instrumentation/); understanding how to instrument and profile serialization performance is critical given the gem's focus on speed
• Object-Relational Mapping (ORM) Agnostic Design — Unlike Active Model Serializer, fast_jsonapi does NOT require ActiveRecord; it works with any Ruby object, making it more flexible but requiring explicit relationship loading strategy (developer must call includes/eager_load)
• Fragment Caching Strategy — fast_jsonapi supports per-attribute caching via set_cache_length_expires_in; this is a performance optimization technique where serialized fragments are memoized, reducing repeated serialization work for unchanged objects
• Mixin-Based DSL Pattern — The serializer uses include FastJsonapi::ObjectSerializer to add DSL methods (attributes, has_many, etc.) to user classes; this pattern is less intrusive than class inheritance but requires understanding Ruby's method resolution order

• jsonapi-serializer/jsonapi-serializer — Direct fork and maintained successor of fast_jsonapi; Netflix explicitly recommends this for new projects
• rails-api/active_model_serializers — The original JSON serializer for Rails that fast_jsonapi was benchmarked against and designed to out-perform (25-46x faster)
• Netflix/pollyjs — Netflix's other open-source project; shows architectural patterns common in Netflix's Ruby ecosystem at time of development
• ruby-json-schema/json-schema — Complementary tool for validating JSON:API responses against schema; often used with fast_jsonapi output in test suites
• thoughtbot/factory_bot — Commonly paired in test suites with fast_jsonapi (see spec/ usage patterns); generates test objects to serialize

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 test coverage for lib/fast_jsonapi/relationship.rb

The relationship.rb file is a core component for handling JSON:API relationships, but there are no dedicated spec files for it in spec/lib/. While relationship functionality is tested indirectly through object_serializer_relationship_*.rb specs, a focused unit test file would ensure edge cases are covered (circular relationships, self-referential relationships, relationship validation errors). This is critical for a serialization library where relationships are fundamental.

• [ ] Create spec/lib/relationship_spec.rb with unit tests for lib/fast_jsonapi/relationship.rb
• [ ] Test relationship initialization, attribute validation, and relationship type handling
• [ ] Add tests for edge cases: missing required attributes, invalid type specifications, and complex relationship configurations
• [ ] Ensure test coverage for all public methods in the Relationship class

Add comprehensive test coverage for lib/fast_jsonapi/link.rb

The link.rb file handles JSON:API link generation, but there are no dedicated unit tests in spec/lib/ (no link_spec.rb exists). While links are tested indirectly through relationship_links tests, direct unit testing of the Link class would ensure proper URL generation, parameter handling, and link type validation. This is essential for API compliance.

• [ ] Create spec/lib/link_spec.rb with unit tests for lib/fast_jsonapi/link.rb
• [ ] Test link initialization, URL generation with various parameter types, and link attribute validation
• [ ] Add tests for edge cases: missing URLs, invalid link types, special characters in URLs, and dynamic link generation
• [ ] Test interaction with the serialization core to ensure links are properly included in output

Add instrumentation tests for lib/fast_jsonapi/instrumentation/skylight.rb integration

The Skylight instrumentation module exists (lib/fast_jsonapi/instrumentation/skylight/ with normalizers), and there's a test file for requiring Skylight normalizers, but there are no actual functional integration tests for Skylight monitoring. Given that instrumentation is critical for production performance analysis (especially for a performance-focused gem), adding tests that verify Skylight events are properly emitted during serialization would ensure monitoring reliability.

• [ ] Create spec/lib/instrumentation/skylight_integration_spec.rb to test actual Skylight integration
• [ ] Mock Skylight's instrumentation API and verify that serialization events are emitted with correct timing and metadata
• [ ] Test both serializable_hash and serialized_json paths through Skylight normalizers
• [ ] Add tests for edge cases: disabled instrumentation, Skylight gem not available, and large collection serialization events

• Add test coverage for lib/extensions/has_one.rb — it appears in file list but has no visible test file (spec/lib/extensions/has_one_spec.rb missing), suggesting untested code path for has_one relationships
• Document the caching API (set_cache_length_expires_in) with concrete examples in README — docs/collection_serializer_output.json and docs/object_serializer.json exist but show output format, not how to configure caching for different attribute types
• Add spec/lib/fast_jsonapi/link.rb tests — lib/fast_jsonapi/link.rb is in the file list but no corresponding spec file visible, leaving link generation behavior untested

This codebase presents significant security concerns primarily due to its unmaintained status. While the serialization library itself does not appear to have obvious injection vulnerabilities in the visible code, the lack of ongoing maintenance means any discovered vulnerabilities will not be patched. The provided dependencies could not be analyzed due to missing manifest content. Critical recommendation: Do not use this library in production. Migrate to the actively maintained fork 'jsonapi-serializer/jsonapi-serializer' or evaluate other maintained alternatives. Additional concerns include potential code execution risks in the generator component and insufficient security documentation.

• High · Unmaintained Project with Known Vulnerabilities — README.md, entire codebase. This project is explicitly marked as 'no longer maintained' in the README. An unmaintained codebase will not receive security patches, bug fixes, or updates for newly discovered vulnerabilities. Dependencies may contain known CVEs that will never be addressed. Fix: Migrate to the maintained fork 'jsonapi-serializer/jsonapi-serializer' or an actively maintained alternative JSON:API serializer. This is critical for production use.
• Medium · Dependency Information Not Provided — Gemfile, fast_jsonapi.gemspec. The Gemfile and gemspec files are listed in the directory structure but their content was not provided for analysis. This prevents verification of dependency versions, known CVEs in transitive dependencies, and supply chain risks. Fix: Provide complete dependency manifests. Run 'bundle audit' to check for known vulnerabilities in all dependencies. Ensure all gems are pinned to specific versions or version ranges that have been security-audited.
• Medium · Potential Dynamic Code Execution in Serializer Generation — lib/generators/serializer/serializer_generator.rb, lib/generators/serializer/templates/serializer.rb.tt. The codebase includes a generator at 'lib/generators/serializer/serializer_generator.rb' that dynamically creates serializer classes. If user input or external data is used without proper validation in the generation process, this could lead to arbitrary code execution. Fix: Review the generator implementation to ensure all user inputs are validated and sanitized. Do not use eval() or similar dynamic code execution methods with untrusted input.
• Medium · Instrumentation and Monitoring Hooks — lib/fast_jsonapi/instrumentation/, lib/fast_jsonapi/instrumentation/skylight/. The codebase contains Skylight instrumentation hooks that could potentially expose sensitive information about serialization patterns, data structures, or performance metrics if misconfigured or if monitoring dashboards are publicly accessible. Fix: Ensure all monitoring and instrumentation endpoints are properly authenticated. Review what data is being collected and transmitted to monitoring services. Ensure no sensitive data (PII, tokens, credentials) is included in instrumentation data.
• Low · No Security Policy or Security.md — Repository root. There is no SECURITY.md file or clear security policy documented. For a library that was maintained by Netflix, this is unusual and suggests insufficient security governance. Fix: Even though the project is unmaintained, create a SECURITY.md file advising users of the maintenance status and directing them to maintained alternatives.
• Low · Potential Information Disclosure via Error Messages — lib/fast_jsonapi/object_serializer.rb, lib/fast_jsonapi/serialization_core.rb. The serializer may output detailed error messages or stack traces that could reveal internal application structure or Ruby version information to potential attackers. Fix: Implement proper error handling that doesn't expose sensitive details. Ensure error messages are sanitized in production environments. Use Rails error handling mechanisms to prevent stack trace leakage.

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.