graphiti 2.0.0.beta.3 → 2.0.0.beta.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69a8294c01d96b3ca136060036e2b8592f46464a775965f6f2e42129915854bd
-  data.tar.gz: e133c0cf444718997a718e16a957b6e11d86aec78696ac2cd4bb4fe8e3b907eb
+  metadata.gz: e8f1b385d0a7623788b2a492d98d2175d1964d320ea48f988f73bffb30ab9439
+  data.tar.gz: a95f11de0a07753144d5c4d057ae0b4bb90e2f61c5906996bd29f7fa09998657
 SHA512:
-  metadata.gz: fb38ebe38f207b016b61a960f0b39890fe4cb3aa8e8bc70a50f5f82894513c9360fe37ce02de50a7de14718d5a0f5865a50d6defe1ce15e2730409bc3324401c
-  data.tar.gz: cc5090ad354c15c4f7d5a2c9daa8aab78be9bc7b4f41c62569a5fa5edf7496dd79e2b0d86533027fd7989ed1f7295950fc325a1cf9475ae03992ddd6344a2e27
+  metadata.gz: 7f00afaae7e44289e89d5d29e56e3539953e2c13befcc6c2d5dbb95c9b8904ca6103c3651ebabb6227f9e43f50f22ee4b845d1d9235244e363a1c08089363c47
+  data.tar.gz: a6f82ed9556a22d2ddd76710877af8f39cfca470cad5a12a05d99ef5d54fc6d03a5c0e549026307cd71b6a6323c51e4889164acd94a38a0d371e0c74fe54760a

data/.github/workflows/ci.yml

@@ -18,105 +18,49 @@ jobs:
       - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.0"
+          ruby-version: "3.2"
           bundler-cache: true
       - name: Run standardrb
         run: bundle exec standardrb --no-fix --format progress
   test:
-    name: "Tests - ${{ matrix.ruby }} | ${{ matrix.gemfile }} | Appraisal: ${{ matrix.appraisal }}"
+    name: "Tests - ${{ matrix.ruby }} | ${{ matrix.gemfile }}"
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
+      # Every cell is listed explicitly rather than built from a cross product
+      # plus `exclude:`. An exclude row naming a gemfile that does not exist is
+      # silently ignored, which is how this matrix carried four dead rows for a
+      # "rails_7_0_graphiti_rails.gemfile" that was never generated. A bad
+      # gemfile path in an include row fails the job loudly instead.
+      #
+      # Ruby coverage per Rails version tracks that version's own supported
+      # range; see Appraisals for the matching sqlite3 constraints.
       matrix:
-        ruby:
-          - "3.0"
-          - "3.1"
-          - "3.2"
-          - "3.3"
-          - "3.4"
-        gemfile:
-          - Gemfile
-          - gemfiles/rails_6.gemfile
-          - gemfiles/rails_7.gemfile
-          - gemfiles/rails_6_graphiti_rails.gemfile
-          - gemfiles/rails_7_graphiti_rails.gemfile
-          - gemfiles/rails_7_1_graphiti_rails.gemfile
-          - gemfiles/rails_7_2_graphiti_rails.gemfile
-          - gemfiles/rails_8_0_graphiti_rails.gemfile
-          - gemfiles/rails_8_1_graphiti_rails.gemfile
-        appraisal:
-          - true
-          - false
         include:
-          - ruby: ruby-head
-            gemfile: gemfiles/rails_7_1.gemfile
-            appraisal: true
-          - ruby: ruby-head
-            gemfile: gemfiles/rails_7_2_graphiti_rails.gemfile
-            appraisal: true
-          - ruby: ruby-head
-            gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
-            appraisal: true
-          - ruby: ruby-head
-            gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
-            appraisal: true
-          - ruby: ruby-head
-            gemfile: Gemfile
-            appraisal: false
-        exclude:
-          # Skip some extra variants
-          - gemfile: Gemfile
-            appraisal: true
-          - gemfile: gemfiles/rails_6.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_7.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_6_graphiti_rails.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_7_graphiti_rails.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_7_1_graphiti_rails.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_7_2_graphiti_rails.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
-            appraisal: false
-          - gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
-            appraisal: false
+          # No Rails - the library on its own, across every supported Ruby
+          - { ruby: "3.2", gemfile: Gemfile, appraisal: false }
+          - { ruby: "3.3", gemfile: Gemfile, appraisal: false }
+          - { ruby: "3.4", gemfile: Gemfile, appraisal: false }
+          - { ruby: ruby-head, gemfile: Gemfile, appraisal: false }
 
-          # Rails 8.1 needs ruby 3.2 +
-          - gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
-            ruby: 3.0
-          - gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
-            ruby: 3.1
+          # Rails 7.1 - the floor
+          - { ruby: "3.2", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
+          - { ruby: "3.4", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
 
-          # Rails 8 needs ruby 3.2 +
-          - gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
-            ruby: 3.0
-          - gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
-            ruby: 3.1
+          # Rails 7.2
+          - { ruby: "3.2", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
+          - { ruby: "3.4", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
+          - { ruby: ruby-head, gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
 
-          # Rails 7.2 needs ruby 3.1 +
-          - gemfile: gemfiles/rails_7_2_graphiti_rails.gemfile
-            ruby: 3.0
+          # Rails 8.0
+          - { ruby: "3.2", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
+          - { ruby: "3.4", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
+          - { ruby: ruby-head, gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
 
-          # Rails 7.1 needs ruby 3.0 +
-          - gemfile: gemfiles/rails_7_1_graphiti_rails.gemfile
-            ruby: 3.0
-
-          # Rails 7.0 needs ruby 3.1 +
-          - gemfile: gemfiles/rails_7_0_graphiti_rails.gemfile
-            ruby: 3.2
-          - gemfile: gemfiles/rails_7_0_graphiti_rails.gemfile
-            ruby: 3.3
-          - gemfile: gemfiles/rails_7_0_graphiti_rails.gemfile
-            ruby: 3.4
-
-          # Rails 6 needs < ruby 3.4
-          - gemfile: gemfiles/rails_6.gemfile
-            ruby: 3.4
-          - gemfile: gemfiles/rails_6_graphiti_rails.gemfile
-            ruby: 3.4
+          # Rails 8.1
+          - { ruby: "3.2", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
+          - { ruby: "3.4", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
+          - { ruby: ruby-head, gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
 
     continue-on-error: ${{ matrix.ruby == 'ruby-head' }}
     env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps

data/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Docs
+
+# Publishes the documentation site from beta so the deploy is exercised well
+# before it matters. Pages serves this repo under /graphiti/, and the root of
+# graphiti.dev comes from graphiti-api.github.io, so nothing here can affect
+# the live 1.x site. When the domain moves to this repo, drop DOCS_BASE_URL so
+# baseUrl returns to "/" and add website/static/CNAME.
+on:
+  push:
+    branches: [beta]
+    paths:
+      - 'docs/**'
+      - 'website/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch: {}
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install
+        working-directory: website
+        run: npm ci
+
+      - name: Build
+        working-directory: website
+        env:
+          DOCS_BASE_URL: /graphiti/
+        run: npm run build
+
+      - name: Publish to gh-pages
+        working-directory: website/build
+        run: |
+          set -euo pipefail
+          # Pages skips directories beginning with an underscore unless Jekyll
+          # is switched off, and Docusaurus emits some.
+          touch .nojekyll
+          git init --quiet --initial-branch=gh-pages
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add --all
+          git commit --quiet -m "docs: build ${GITHUB_SHA::7} from ${GITHUB_REF_NAME}"
+          git push --force --quiet \
+            "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" \
+            gh-pages

data/.github/workflows/release.yml

@@ -10,27 +10,27 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v5
         with:
-          submodules: true
           persist-credentials: false
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.1"
+          ruby-version: "3.4"
       - name: Build
         run: |
           gem install bundler
-          git submodule update --init --recursive
           bundle install --jobs 4 --retry 3
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: 14
+          # semantic-release 25 and its plugins require ^22.22.2 || >=24.15
+          node-version: "24"
+          cache: npm
       - name: Install Dependencies
-        run: yarn install --frozen-lockfile
+        run: npm ci
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GEM_HOST_API_KEY: ${{ secrets.GEM_HOST_API_KEY }}
-        run: node_modules/.bin/semantic-release
+        run: npx semantic-release

data/.gitignore

@@ -15,3 +15,10 @@ spec/.rspec-examples
 spec/dummy/log/*
 *~
 .vscode/
+
+# Docusaurus
+website/build/
+website/.docusaurus/
+
+.DS_Store
+.idea/

data/.npmrc

@@ -0,0 +1,9 @@
+# semantic-release-rubygem@1.2.0 declares `peerDependencies: { semantic-release:
+# ">=16.0.0 <18.0.0" }`, but it was last published in July 2020 and that range has
+# simply not been updated since. This project has been releasing against
+# semantic-release 19 for years, and the plugin loads cleanly under 25 exposing
+# its verifyConditions/prepare/publish hooks - it only touches `env` and `cwd` on
+# the plugin context, both stable across semantic-release majors.
+#
+# Without this, `npm ci` fails the install with ERESOLVE.
+legacy-peer-deps=true

data/.standard.yml

@@ -1,9 +1,12 @@
 fix: true
 parallel: true
-ruby_version: 3.0
+ruby_version: 3.2
 
 ignore:
   - 'vendor/**/*'
+  # The docs site, including the frozen 1.x archive under static/. None of it
+  # is ours to restyle, and some of it is generated.
+  - 'website/**/*'
   - 'spec/**/*':
     # There are some false hits when doing repeated
     # Class.new blocks in different test cases

data/Appraisals

@@ -1,45 +1,46 @@
-appraise "rails-6" do
-  gem "rails", "~> 6.0"
-  gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
-end
-
-appraise "rails-6-graphiti-rails" do
-  gem "rails", "~> 6.0"
-  gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
-  gem "graphiti-rails", "~> 0.4.0"
-end
+# Graphiti's Rails integration ships in the gem itself as of 2.0, so there is
+# one appraisal per Rails version rather than a with/without graphiti-rails pair.
+#
+# Rails 7.1 is the floor: 2.0 requires Ruby >= 3.2, and Rails 6.1 and 7.0 do not
+# support it. Apps on older Rails stay on the graphiti 1.x branch.
+#
+# Every Rails requirement pins the minor ("~> 7.1.0", not "~> 7.1"). The looser
+# form lets a newer minor satisfy it, which is how rails-7-1 and rails-8-0 ended
+# up resolving to 7.2 and 8.1 - two appraisals apiece testing the same Rails and
+# neither testing the version it was named for.
+#
+# sqlite3 pins follow what each Rails version's adapter demands at require time
+# (activerecord/lib/active_record/connection_adapters/sqlite3_adapter.rb):
+#   Rails 7.1       -> gem "sqlite3", "~> 1.4"   (2.x raises Gem::LoadError)
+#   Rails 7.2       -> gem "sqlite3", ">= 1.4"
+#   Rails 8.0 / 8.1 -> gem "sqlite3", ">= 2.1"
+# "~> 1.4" rather than "~> 1.4.0" is deliberate: it resolves to 1.7.x, which
+# still builds on modern Rubies, where 1.4.x no longer does.
 
-appraise "rails-7" do
-  gem "rails", "~> 7.0"
+appraise "rails-7-1" do
+  gem "rails", "~> 7.1.0"
   gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
+  gem "responders"
+  gem "sqlite3", "~> 1.4"
 end
 
-appraise "rails-7-graphiti-rails" do
-  gem "rails", "~> 7.0"
+appraise "rails-7-2" do
+  gem "rails", "~> 7.2.0"
   gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
-  gem "graphiti-rails", "~> 0.4.0"
+  gem "responders"
+  gem "sqlite3", "~> 2.1"
 end
 
-appraise "rails-7-1" do
-  gem "rails", "~> 7.1"
+appraise "rails-8-0" do
+  gem "rails", "~> 8.0.0"
   gem "rspec-rails"
-  # This appraisal is the ruby-head job; sqlite3 1.4.x cannot build on Ruby 4.x
+  gem "responders"
   gem "sqlite3", "~> 2.1"
-  gem "database_cleaner"
 end
 
-appraise "rails-7-1-graphiti-rails" do
-  gem "rails", "~> 7.1"
+appraise "rails-8-1" do
+  gem "rails", "~> 8.1.0"
   gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
-  gem "graphiti-rails", "~> 0.4.0"
+  gem "responders"
+  gem "sqlite3", "~> 2.1"
 end

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 graphiti changelog
 
+# [2.0.0-beta.4](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.3...v2.0.0-beta.4) (2026-08-07)
+
+
+### Bug Fixes
+
+* a subclass redeclaring a relationship reaches its serializer ([976dbc4](https://github.com/graphiti-api/graphiti/commit/976dbc47e7bbf951da925a13a34f1bc9679470f8))
+* make each appraisal test the Rails version it is named for ([9e00652](https://github.com/graphiti-api/graphiti/commit/9e00652e124a411a2916d0fef52dc4fd2dc59020))
+* require active_support so graphiti boots without Rails ([d431a03](https://github.com/graphiti-api/graphiti/commit/d431a0328fb4071429f39f4c69cda9c6cee308f2))
+
+
+### Code Refactoring
+
+* bridge the remaining 1.x names ([3d80ef9](https://github.com/graphiti-api/graphiti/commit/3d80ef98cf765a152032b7fed89b3cdc10be23dc))
+
+
+### Features
+
+* belongs_to renders resource linkage by default ([024824d](https://github.com/graphiti-api/graphiti/commit/024824d319619811ade886c72ce345cfeb584dbc)), closes [#168](https://github.com/graphiti-api/graphiti/issues/168) [#185](https://github.com/graphiti-api/graphiti/issues/185) [#167](https://github.com/graphiti-api/graphiti/issues/167) [#167](https://github.com/graphiti-api/graphiti/issues/167)
+* fold graphiti_spec_helpers into graphiti ([da955a1](https://github.com/graphiti-api/graphiti/commit/da955a1e090ba44be31bf043ed90baa6661a4772))
+* fold graphiti-rails into graphiti ([7740f8a](https://github.com/graphiti-api/graphiti/commit/7740f8a5803f1fbf02ef4e27d8baa6e0809d2b43)), closes [graphiti-rails#52](https://github.com/graphiti-rails/issues/52)
+* handle exceptions with rescue_registry, fold in graphiti_errors ([e48171c](https://github.com/graphiti-api/graphiti/commit/e48171c117e7b8141fb6f966a972b0c1cd50c5ab))
+* require Ruby 3.2 and Rails 7.1 ([635b249](https://github.com/graphiti-api/graphiti/commit/635b249a99f7d1ef726ae2328707ee6210cc0608))
+
+
+### BREAKING CHANGES
+
+* nothing removed, everything warns and goes away in 3.0. Except `include GraphitiErrors`, which now raises, as rescue_registry replaced it, so there's nothing to point it at.
+* graphiti_errors is no longer a dependency and must be removed from the Gemfile, along with any `include GraphitiErrors`.
+
+GraphitiErrors::Validation::Serializer is now Graphiti::ErrorSerializers::Validation, and GraphitiErrors.enable!/disable! becomes handle_request_exceptions. 409 responses now report code "conflict" and title "Conflict Error".
+* Ruby >= 3.2 and Rails >= 7.1 are now required.
+* remove graphiti-rails from your Gemfile. Controllers serving Graphiti resources must `include Graphiti::Rails::Controller` — previously every controller received it whether it wanted it or not. Graphiti::Responders is now Graphiti::Rails::Responders.
+* remove graphiti_spec_helpers from your Gemfile. Prefer Graphiti::SpecHelpers and "graphiti/spec_helpers/rspec"; the old namespace and require paths still resolve, warn, and are removed in 3.0.
+
 # [2.0.0-beta.3](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.2...v2.0.0-beta.3) (2026-07-31)
 
 

data/README.md

@@ -55,7 +55,18 @@ class EmployeeResource < ApplicationResource
 end
 ```
 
-A pretty boilerplate controller that just interfaces with the resource
+In Rails, controllers serving resources include `Graphiti::Rails::Controller`. Putting it in `ApplicationController` covers the whole app; putting it in an API base class scopes it there and leaves the rest alone.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Graphiti::Rails::Controller
+end
+```
+
+That gives those controllers the Graphiti context, the debugger, and JSON:API rendering for Graphiti's exceptions plus anything else raised. Registering your own exceptions does not require it — `register_exception` is available on every controller — but only controllers with the include render *unregistered* exceptions as JSON:API rather than falling through to Rails.
+
+A pretty boilerplate controller that just interfaces with the resource. `respond_with` comes from the [`responders`](https://github.com/heartcombo/responders) gem; with it in your Gemfile, add `include Graphiti::Rails::Responders` as well. Otherwise use `render jsonapi:` as the write actions below do.
+
 ```ruby
 class EmployeesController < ApplicationController
   def index
@@ -219,7 +230,7 @@ Request:
 
 
 
-[Graphiti Guides](https://www.graphiti.dev/guides/)
+[Graphiti Documentation](https://www.graphiti.dev/)
 
 [Join the Discord](https://discord.gg/wgqkMBsSRV)
 

data/UPGRADING.md

@@ -1,61 +1,5 @@
 # Upgrading Graphiti
 
-## 1.x to 2.0
+The upgrade guide lives with the rest of the documentation, so it can link into the concept pages and offer the same version picker: **https://www.graphiti.dev/upgrading**
 
-### Requirements
-
-Graphiti 2.0 requires Ruby 3.0+ and Rails 6.0+ (when using Rails).
-
-### The model you inspect is the model that saves
-
-Proxies returned by `build` and `find` now apply the request payload lazily, and expose the resulting model before anything is written:
-
-```ruby
-# Creates
-resource = MyResource.build(params)
-resource.data          # unsaved model, attributes applied
-resource.data.valid?   # inspect before committing to anything
-resource.save          # persists that same instance
-
-# Updates
-resource = MyResource.find(params)
-resource.assign_attributes(params)
-resource.data.changed  # dirty tracking works
-resource.update
-
-# or assign and save in one call, Rails-style
-resource = MyResource.find(params)
-resource.update(params)
-```
-
-`assign_attributes` is idempotent per payload, validation still runs before assignment, and the instance you inspect is the instance that saves.
-
-### Breaking: around_persistence receives the model, not the attributes hash
-
-To make the above hold, attributes are assigned to the model once, before the persistence hooks fire. `around_persistence` now wraps the save of an already-assigned model and receives that model:
-
-```ruby
-# 1.x
-def do_around_persistence(attributes)
-  attributes[:tenant_id] = current_tenant.id
-  model = yield
-  model.log_saved!
-end
-
-# 2.0
-def do_around_persistence(model)
-  model.tenant_id = current_tenant.id # last chance to touch the model before save, inside the transaction
-  saved = yield
-  saved.log_saved!
-end
-```
-
-To migrate, move attribute-hash modifications to `before_attributes` (which still receives the mutable hash, before assignment), or set the value on the model as above. Hooks that only wrap their yield - transactions, timing, post-save side effects - need no changes. Graphiti 1.x releases warn at runtime when a hook would be affected.
-
-`before/around/after_attributes` and `before/around/after_save` are unchanged.
-
-### Fine print
-
-- If you inspect the model before saving, the attributes callbacks run at inspection time (in your controller, outside the save transaction). On the plain `save` path they run inside the transaction, at the same point as 1.x.
-- Writable guards judge persisted state: a guard asking for the model gets a fresh build/find, never the current request's unsaved changes. A payload cannot influence its own authorization.
-- Sideposted child models are still built and assigned during save; `data` exposes the pre-assigned root model only.
+In this repository it is [docs/upgrading/](docs/upgrading/index.md).

data/docs/concepts/backends-and-models.md

@@ -0,0 +1,122 @@
+---
+title: 'Backends and Models'
+---
+
+# Backends and Models
+
+A Resource queries a **Backend** and returns **Models** from what comes back. Graphiti serializes the Models.
+
+With ActiveRecord those are the same object. `Employee` is both the thing you query and the thing you render, and you can skip most of this page. It matters when they're separate: a search index, an HTTP service, a document store. Then the Backend is whatever you query, and the Model is whatever you hand back.
+
+## Scopes {#scopes}
+
+A **scope** is whatever your backend needs to run a query. Graphiti doesn't care what it is. For ActiveRecord it's an `ActiveRecord::Relation`. Here it's a plain hash:
+
+```ruby
+class EmployeeResource < ApplicationResource
+  self.adapter = Graphiti::Adapters::Null
+
+  attribute :name, :string
+
+  def base_scope
+    { conditions: {}, sort: {} }
+  end
+
+  filter :name do
+    eq do |scope, value|
+      scope[:conditions].merge!(value)
+      scope
+    end
+  end
+
+  sort :name do |scope, direction|
+    scope[:sort] = { name: direction }
+    scope
+  end
+
+  def resolve(scope)
+    results = Backend.query(scope)
+    results.map { |result| Employee.new(result) }
+  end
+end
+```
+
+`base_scope` is the starting point, each `filter` and `sort` block mutates it based on request params, and `resolve` runs the query and returns Models.
+
+**Every block must return the scope.** Returning the result of `merge!` or an assignment instead of the scope itself is the most common way to break this.
+
+Writing that per Resource gets old. Once the pattern stabilizes, move it into an [Adapter](/topics/without-activerecord#adapters) and Resources go back to being declarative:
+
+```ruby
+class EmployeeResource < ApplicationResource
+  self.adapter = BackendAdapter
+  attribute :name, :string
+end
+```
+
+## What a Model has to do {#model-requirements}
+
+**Respond to `id`, uniquely.** Graphiti uses `model.id` to tell records apart when rendering. Duplicate ids produce wrong output, not an error.
+
+If the underlying record has no id, generate one:
+
+```ruby
+def id
+  @id ||= SecureRandom.uuid
+end
+```
+
+**Respond to its readable attributes.** `attribute :name, :string` calls `model.name`. If your Model doesn't have that method, pass a block instead:
+
+```ruby
+attribute :name, :string do
+  @object.full_name
+end
+```
+
+**Include `ActiveModel::Validations` if you want validation errors.** Graphiti checks models on write requests and renders a [JSON:API errors payload](http://jsonapi.org/format/#errors) from `model.errors`. Without it, an invalid model saves silently:
+
+```ruby
+class Employee
+  include ActiveModel::Validations
+
+  validates :name, presence: true
+end
+```
+
+## Writing a Model {#model-implementations}
+
+Graphiti has no opinion here. A plain class works:
+
+```ruby
+class Employee
+  attr_accessor :id, :first_name, :last_name, :age
+
+  def initialize(attrs = {})
+    attrs.each_pair { |key, value| send(:"#{key}=", value) }
+  end
+end
+```
+
+[ActiveModel::Model](https://api.rubyonrails.org/classes/ActiveModel/Model.html) gives you the constructor and validations for free:
+
+```ruby
+class Employee
+  include ActiveModel::Model
+
+  attr_accessor :id, :first_name, :last_name, :age
+end
+```
+
+[Dry::Struct](https://dry-rb.org/gems/dry-struct) adds type enforcement, and dry-types is already a Graphiti dependency:
+
+```ruby
+class Employee < Dry::Struct
+  attribute :id, Types::Integer
+  attribute :first_name, Types::String
+  attribute :last_name, Types::String
+  attribute :age, Types::Integer
+end
+```
+
+`OpenStruct` also works and is what Graphiti uses internally for remote resources, but it fails quietly in ways the others don't. See [OpenStruct Models](/topics/openstruct-models) before reaching for it.