diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 2e35d04..77c2736 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -45,8 +45,8 @@ jobs:
       - name: Typecheck example app
         run: pnpm -C examples/blog typecheck
 
-      # Lint must run before migrations: `node ace migration:run` regenerates
-      # database/schema.ts without formatting, which would fail prettier
+      # database/schema.ts is regenerated unformatted by migrations and is
+      # prettier-ignored, so lint and migration order no longer matters
       - name: Lint example app
         run: pnpm -C examples/blog lint
 
diff --git a/README.md b/README.md
index 85ffd9a..d2c1f7a 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,7 @@ Models without a resource class serialize automatically, with the type, attribut
 | [What is JSON:API?](./docs/what-is-jsonapi.md)   | The ideas behind the spec                                                                     |
 | [Reading data](./docs/reading-data.md)           | Resources and types, customizing, `include`, sparse fieldsets, sorting, pagination, filtering |
 | [Writing data](./docs/writing-data.md)           | Create, update and delete from JSON:API documents, relationship endpoints                     |
+| [Polymorphism](./docs/polymorphism.md)           | Mixed-type relationships: the database shapes, trade-offs, and single-table inheritance       |
 | [Links](./docs/links.md)                         | Route-driven URL generation, API versioning, casing                                           |
 | [Errors & negotiation](./docs/errors.md)         | Error documents, `handlesErrors()`, media type rules                                          |
 | [Low-level building blocks](./docs/low-level.md) | Serializing outside a request: commands, jobs, tests                                          |
diff --git a/docs/low-level.md b/docs/low-level.md
index 710b925..22839a8 100644
--- a/docs/low-level.md
+++ b/docs/low-level.md
@@ -115,7 +115,7 @@ const registry = await app.container.make(JsonApiRegistry)
 const input = deserializeResourceDocument(Article, registry, payload, {
   allowClientIds: false,
 })
-await verifyRelatedExist(Article, input.references) // 404-style JsonApiException if missing
+await verifyRelatedExist(Article, input.references, registry) // 404-style JsonApiException if missing
 
 const article = await Article.create(input.attributes)
 ```
diff --git a/docs/polymorphism.md b/docs/polymorphism.md
new file mode 100644
index 0000000..dbb94a6
--- /dev/null
+++ b/docs/polymorphism.md
@@ -0,0 +1,433 @@
+# Polymorphic relationships
+
+A relationship is polymorphic when its members are not all the same kind of thing. A fan's favourites list holds football teams and rugby teams. An article's attachments are images and videos. A feed mixes posts, photos, and links. One relationship holds several kinds of member.
+
+In JSON:API terms, that means resource linkage whose identifiers carry different `type` values:
+
+```jsonc
+"favourites": {
+  "data": [
+    { "type": "football-teams", "id": "1" },
+    { "type": "rugby-teams", "id": "2" }
+  ]
+}
+```
+
+Client-side data libraries expect exactly this shape. [WarpDrive's polymorphism guide](https://warp-drive.io/guides/the-manual/misc/relational-data/features/polymorphism), for instance, is explicit that linkage should carry the concrete type, not an abstract umbrella type, because `type` + `id` is a resource's whole identity and an umbrella type creates a second identity for the same row.
+
+## Single-table inheritance
+
+Databases offer several ways to build the shape, such as one table per type joined by id, or Laravel-style `imageable_type` + `imageable_id` column pairs, which Lucid has no native relations for. This package supports one of them, **single-table inheritance (STI)**. All the types share one table, and a discriminator column says which type each row is, with columns only some types use sitting null on the others:
+
+```
+sports_teams
+  id   name       sport      league_tier   scrum_wins
+  1    Arsenal    football   1             NULL
+  2    Saracens   rugby      NULL          312
+```
+
+With one shared table, the database layer already works. Anything pointing at the family is an ordinary foreign key, a mixed to-many is an ordinary pivot, and plain `belongsTo` / `hasMany` / `manyToMany` declared against the base class work mechanically. Subclasses set `static table` to the shared table and scope their queries to their discriminator value.
+
+The only thing left to solve is _naming_, and it is a serialization problem, not a Lucid one. Lucid hydrates a relation's rows as the relation's declared target, the base class, which is correct behaviour for an ORM with no concept of a discriminator. The row still carries its discriminator column. Without the declarations on this page, the serializer derived a row's JSON:API type from its class rather than from the row, so base-hydrated rows serialized under the base type, and writes compared incoming identifiers against the one declared target type. Teaching the serializer to ask the row is what the rest of this page describes.
+
+Declaring nothing is also workable. The base serializes as one `sports-teams` type, the discriminator rides along as an ordinary attribute, and clients branch on it. Nothing in JSON:API forbids that, and for an API that is content to mirror its database it is less machinery. The declarations below exist so the API does not have to mirror the schema. Clients see `football-teams` and `rugby-teams` as if each had its own table, the shared table stays an implementation detail, and storage can be reorganized later without renaming anything a client depends on.
+
+## Declaring the family
+
+Lucid's own serialization needs none of what follows. `row.serialize()` emits the columns, the discriminator among them, and that is all anyone expects of it, so with plain Adonis serialization STI simply works. JSON:API asks for more. Every resource object and every identifier must carry a `type`, and the correct type for an STI row is the concrete one. The declarations in this section are that extra effort. They hand the serializer the mapping from a row to its concrete type, which the model definitions alone do not carry.
+
+The examples below use one family. `SportsTeam` is the base, `FootballTeam` and `RugbyTeam` share its table, and `sport` is the discriminator.
+
+```ts
+// app/models/sports_team.ts
+export default class SportsTeam extends BaseModel {
+  static table = 'sports_teams'
+
+  /**
+   * The discriminator value each subclass owns. Null on the base. The
+   * base stays unscoped, so a relation targeting it can hold the whole
+   * family.
+   */
+  static readonly teamSport: 'football' | 'rugby' | null = null
+
+  @column() declare name: string
+  @column() declare sport: 'football' | 'rugby'
+
+  /**
+   * Scopes subclass queries to their discriminator, so
+   * FootballTeam.query() only ever sees football rows. find/findOrFail/
+   * first inherit the scope because they build on query().
+   */
+  static query<Model extends LucidModel, Result = InstanceType<Model>>(
+    this: Model,
+    options?: ModelAdapterOptions
+  ): ModelQueryBuilderContract<Model, Result> {
+    const query = super.query(options) as unknown as ModelQueryBuilderContract<Model, Result>
+    const sport = (this as unknown as typeof SportsTeam).teamSport
+    if (sport) query.where('sport', sport)
+    return query
+  }
+
+  /**
+   * Rows created through a subclass carry its discriminator without the
+   * caller spelling it out.
+   */
+  @beforeCreate()
+  static assignSport(row: SportsTeam) {
+    const sport = (row.constructor as typeof SportsTeam).teamSport
+    if (sport && !row.sport) row.sport = sport
+  }
+}
+
+export class FootballTeam extends SportsTeam {
+  static table = 'sports_teams'
+  static readonly teamSport = 'football' as const
+}
+
+export class RugbyTeam extends SportsTeam {
+  static table = 'sports_teams'
+  static readonly teamSport = 'rugby' as const
+}
+
+// app/models/fan.ts
+export default class Fan extends BaseModel {
+  @manyToMany(() => SportsTeam, { pivotTable: 'favourites' })
+  declare favourites: ManyToMany<typeof SportsTeam>
+}
+```
+
+`Fan.favourites` is the relation that needs the declarations. It targets the base, so Lucid hydrates its rows as `SportsTeam` and only the discriminator says what each one is. Contrast a direct query. `FootballTeam.query()` hydrates `FootballTeam` instances, the class itself names the type, and those rows serialize as `football-teams` with no help. Giving base-targeted rows the same treatment takes two statics on the base resource. Each resource stays in its own file, scaffolded with `node ace make:jsonapi:resource`, and the subtype resources are ordinary resources:
+
+```ts
+// app/resources/football_team_resource.ts
+export default class FootballTeamResource extends JsonApiResource<FootballTeam> {
+  static type = 'football-teams'
+  static model = () => FootballTeam
+}
+
+// app/resources/rugby_team_resource.ts
+export default class RugbyTeamResource extends JsonApiResource<RugbyTeam> {
+  static type = 'rugby-teams'
+  static model = () => RugbyTeam
+}
+```
+
+The base resource imports them and declares the family:
+
+```ts
+// app/resources/sports_team_resource.ts
+import FootballTeamResource from '#resources/football_team_resource'
+import RugbyTeamResource from '#resources/rugby_team_resource'
+
+export default class SportsTeamResource extends JsonApiResource<SportsTeam> {
+  static model = () => SportsTeam
+  static subtypes = () => [FootballTeamResource, RugbyTeamResource]
+  static resolveResource(row: SportsTeam) {
+    return { football: FootballTeamResource, rugby: RugbyTeamResource }[row.sport]
+  }
+}
+```
+
+`resolveResource` serves reads. It takes a row and returns its concrete resource, typically by reading the discriminator, and returning `undefined` keeps the row on the base resource. `subtypes` serves writes. It lists the types a relation targeting the base accepts.
+
+The two look similar but answer opposite questions, and neither can be derived from the other. When serializing, the input is a hydrated row, and the question is which one resource it belongs to, which only a function can answer. When validating a write, the input is a type string from the request body, and no row exists yet because the check runs before any database access, so the question is whether the string belongs to the family, and that needs the family as a list, which cannot be computed out of an opaque function.
+
+Register all three in the config, the same as any other resource:
+
+```ts
+// config/jsonapi.ts
+resources: [
+  () => import('#resources/sports_team_resource'),
+  () => import('#resources/football_team_resource'),
+  () => import('#resources/rugby_team_resource'),
+]
+```
+
+The base also registers its declared subtypes as a safety net. Registration is what gives a direct query its type, so a subtype missing from the map would make `FootballTeam.query()` rows serialize under an auto-derived type, and the safety net prevents that silent degradation when an entry is forgotten. It never overrides you. An explicitly registered resource for a subtype's model always wins over the base's declaration.
+
+## Families discovered at runtime
+
+So far the family has been fixed. Football and rugby are known while the code is written, so each subtype gets a model, a resource file, and a config entry.
+
+Some applications cannot know the family upfront, because the types are made by users. A form builder where users define their own field kinds. A CMS where editors invent content types. A tracker where each workspace declares its own item categories. The rows still live in one table with a discriminator column, since a table per kind would need a migration every time a user invents one, but the discriminator's values are data, created at runtime, different in every installation. There is no moment at which a developer can write `football_team_resource.ts`, because nobody knows what the kinds will be.
+
+The declarations still work, because both are functions. Nothing forces `subtypes()` to return classes that exist as files, and nothing forces `resolveResource` to pick from a fixed set. A base resource can build concrete resources on demand, keyed on discriminator values that are themselves user data:
+
+```ts
+// app/resources/team_resource.ts
+const cache = new Map<string, JsonApiResourceClass>()
+
+export function resourceForSport(sport: string) {
+  let resource = cache.get(sport)
+  if (!resource) {
+    // the discriminator value doubles as the JSON:API type, so one
+    // vocabulary covers the column, the URL, and the documents
+    resource = class extends TeamResource {
+      static type = sport
+    }
+    cache.set(sport, resource)
+  }
+  return resource
+}
+
+export default class TeamResource extends JsonApiResource<SportsTeam> {
+  static model = () => SportsTeam
+  static subtypes = () => [...cache.values()]
+  static resolveResource(row: SportsTeam) {
+    return resourceForSport(row.sport)
+  }
+}
+```
+
+Three details make this work.
+
+- **One class per value, memoized.** The registry caches type strings per class object, and the resolution walk ends when it sees a repeated class, so the same discriminator value must always resolve to the same class. The `Map` provides that identity.
+- **`subtypes()` is consulted on every write**, never captured at boot. The moment a new kind lands in the cache, writes naming its type are accepted. Before any kind exists, the accepted set is empty and every write is a 409.
+- **Inheriting from the base resource is safe.** The runtime-built class inherits `resolveResource`, and resolving again returns the same memoized class, which ends the walk. It also inherits `exposeRelationships`, `filters`, and any attribute customization, so the family shares the base's behaviour by default.
+
+How kinds enter the cache is the application's decision, and the choice shows on writes. Filled lazily, as above, a kind's type is only accepted after some row of that kind has been serialized once. Seeded at boot, every known kind is accepted from the first request. Seeding is a preload file that reads the kinds from wherever they are defined, here the distinct discriminator values already in the table:
+
+```ts
+// start/team_kinds.ts
+import db from '@adonisjs/lucid/services/db'
+import { resourceForSport } from '#resources/team_resource'
+
+const rows = await db.from('sports_teams').distinct('sport')
+for (const { sport } of rows) {
+  resourceForSport(sport)
+}
+```
+
+Registered in `adonisrc.ts` so it runs at boot, restricted to the web environment:
+
+```ts
+preloads: [{ file: () => import('#start/team_kinds'), environment: ['web'] }]
+```
+
+The restriction matters. Preloads also run when ace commands boot the app, and on a fresh database the table does not exist until `migration:run` finishes, so a preload that reads it would crash the very command that creates it. Web-only registration keeps the seed out of console commands and tests, where rows are seeded per test anyway.
+
+A kind created after boot is registered where it is created. The endpoint or service that saves a new kind calls `resourceForSport` as part of the same operation, so the seed covers everything known at boot and the create path covers everything after.
+
+Runtime kinds cannot have routes registered per type, so their endpoints are wildcard routes over the base model:
+
+```ts
+// GET /api/v1/:type
+async index({ jsonApi, params }: HttpContext) {
+  const teams = await jsonApi.query(SportsTeam).where('sport', params.type).paginate(...)
+  return jsonApi.render(teams)
+}
+
+// POST /api/v1/:type
+async store({ jsonApi, params }: HttpContext) {
+  const input = await jsonApi.deserialize(SportsTeam, { expectedType: params.type })
+  const team = await SportsTeam.create({ ...input.attributes, sport: input.type })
+  return jsonApi.render(team, { status: 201 })
+}
+```
+
+Reads need nothing special, because every row is named through `resolveResource` regardless of which endpoint served it. Writes lean on two things. Deserializing against an STI base accepts any member of the declared family, and `expectedType` narrows that to the one type the URL names, so a body claiming a different member is a 409. The result carries the validated `type` back, which is also how an endpoint without a type in its URL would decide which discriminator to stamp.
+
+The controllers trust `params.type`, so validate it against the known kinds first and 404 the rest. `expectedType` pins the body to the URL, and it accepts whatever string it is given, so an unvalidated URL segment would let a made-up kind straight through to the row.
+
+None of this shape is prescribed by the package. The cache, the factory, and the seeding are ordinary application code, and the package only ever calls the two declared functions. The example exists to show how much room those two functions leave.
+
+## What documents look like
+
+Rows resolve to concrete types everywhere they appear, in primary data, linkage, `included` (deduplicated under the concrete type), and relationship-endpoint GETs. Sparse fieldsets key on the concrete type (`fields[football-teams]=name`).
+
+```jsonc
+// GET /fans/1?include=favourites
+{
+  "data": {
+    "type": "fans",
+    "id": "1",
+    "relationships": {
+      "favourites": {
+        "data": [
+          { "type": "football-teams", "id": "1" },
+          { "type": "rugby-teams", "id": "2" },
+        ],
+      },
+    },
+  },
+  "included": [
+    { "type": "football-teams", "id": "1", "attributes": { "name": "Arsenal" } },
+    { "type": "rugby-teams", "id": "2", "attributes": { "name": "Saracens" } },
+  ],
+}
+```
+
+The relationship endpoint serves the same concrete linkage:
+
+```jsonc
+// GET /fans/1/relationships/favourites
+{
+  "jsonapi": { "version": "1.1" },
+  "data": [
+    { "type": "football-teams", "id": "1" },
+    { "type": "rugby-teams", "id": "2" },
+  ],
+  "links": {
+    "self": "/fans/1/relationships/favourites",
+    "related": "/fans/1/favourites",
+  },
+}
+```
+
+The abstract type (`sports-teams`) never appears in a payload. Clients see a family of concrete types over one shared id space, which is what client caches expect of polymorphic data.
+
+## Writes
+
+A relation targeting the base accepts any member of the family, in any mix. Adding a rugby team to favourites that already hold a football team:
+
+```jsonc
+// POST /fans/1/relationships/favourites
+{ "data": [{ "type": "rugby-teams", "id": "2" }] }
+
+// 200
+{
+  "jsonapi": { "version": "1.1" },
+  "data": [
+    { "type": "football-teams", "id": "1" },
+    { "type": "rugby-teams", "id": "2" },
+  ],
+  "links": {
+    "self": "/fans/1/relationships/favourites",
+    "related": "/fans/1/favourites",
+  },
+}
+```
+
+A type outside the family is a `409` naming every acceptable type. The abstract base type is rejected the same way, it never belongs in a payload:
+
+```jsonc
+// POST /fans/1/relationships/favourites
+{ "data": [{ "type": "referees", "id": "1" }] }
+
+// 409
+{
+  "jsonapi": { "version": "1.1" },
+  "errors": [
+    {
+      "status": "409",
+      "title": "Conflict",
+      "detail": "This relationship holds resources of type \"football-teams\" or \"rugby-teams\"",
+      "source": { "pointer": "/data" },
+    },
+  ],
+}
+```
+
+A claimed type the row's discriminator contradicts is a `404`. The family shares one id space, so any id "exists" for any subtype, and the claimed type has to be checked against the row. Row 2 exists, but it is a rugby team, so `football-teams/2` names a resource that does not exist, and an existence check alone would attach it silently:
+
+```jsonc
+// POST /fans/1/relationships/favourites
+{ "data": [{ "type": "football-teams", "id": "2" }] }
+
+// 404
+{
+  "jsonapi": { "version": "1.1" },
+  "errors": [
+    {
+      "status": "404",
+      "title": "Not Found",
+      "detail": "Related resources do not exist: football-teams/2",
+      "source": { "pointer": "/data/relationships/favourites" },
+    },
+  ],
+}
+```
+
+`verifyRelatedExist` performs the discriminator check, which is why the function takes the registry.
+
+## The one place a type cannot be known
+
+Resource linkage for an unloaded belongsTo is normally derived from the bare foreign key, without touching the database. With STI that derivation is impossible, because the discriminator lives on the target row, and the foreign key is just an id. Suppose a stadium belongs to a team:
+
+```ts
+export default class Stadium extends BaseModel {
+  @column() declare teamId: number
+
+  @belongsTo(() => SportsTeam, { foreignKey: 'teamId' })
+  declare team: BelongsTo<typeof SportsTeam>
+}
+```
+
+Fetching a stadium on its own leaves `team` unloaded. If the serializer guessed from the foreign key anyway, the id would come from `team_id` and the only type it could name is the relation's declared target, the base:
+
+```jsonc
+// GET /stadiums/9, as it would look if the guess were made
+{
+  "data": {
+    "type": "stadiums",
+    "id": "9",
+    "attributes": { "name": "Emirates" },
+    "relationships": {
+      "team": {
+        // team_id = 1, and the declared target is SportsTeam
+        "data": { "type": "sports-teams", "id": "1" },
+        "links": {
+          "self": "/stadiums/9/relationships/team",
+          "related": "/stadiums/9/team",
+        },
+      },
+    },
+  },
+}
+```
+
+Row 1 is a football team, so the true identity of this resource is `football-teams/1`, and that is what every other document calls it. This one calls it `sports-teams/1`. That one guess causes three problems.
+
+- The identity never resolves. No endpoint serves `sports-teams`, so nothing a client does with `sports-teams/1` produces a resource. Following the `related` link works, but it returns `football-teams/1`, which does not match the linkage that pointed at it.
+- It forks client caches. A cache keys resources by `type` + `id`, so when the same row arrives through any other path, a favourites list, a direct fetch, it lands as `football-teams/1` and the cache now holds two records for one row, the abstract one empty forever.
+- It dead-ends type-keyed client logic. Code that routes from linkage, opening a team page for `football-teams` or `rugby-teams`, has no branch for `sports-teams`.
+
+In a compound document the same guess also violates the spec's full-linkage rule, since the row can sit in `included` under its concrete type while the guessed identifier dangles.
+
+So the package refuses to guess. An unloaded belongsTo targeting an STI base emits the relationship member with **no `data`**, keeping its `links`:
+
+```jsonc
+"team": {
+  "links": {
+    "self": "/stadiums/9/relationships/team",
+    "related": "/stadiums/9/team",
+  },
+}
+```
+
+A client that needs the target follows the `related` link and gets the concrete type from the loaded row. Loading the relation (or including it) always yields full concrete linkage. Relations targeting a concrete subclass, or any non-STI model, keep FK-derived linkage exactly as before.
+
+## Custom type schemes
+
+Type derivation lives in one overridable method on the resource, consulted for models and rows alike:
+
+```ts
+static typeName(): string {
+  return this.type ?? string.dashCase(this.model().table)
+}
+```
+
+Override it on a resource to compute types under a different scheme; the registry honours it everywhere, including subtype resolution.
+
+## Should you design your schema this way?
+
+Polymorphic schemas have a poor reputation, and the criticism is fair. A relational schema is supposed to declare what the data is and have the database enforce it, and every polymorphic shape gives some of that up. A morph column pair cannot be a real foreign key, an STI table cannot mark a subtype's column `NOT NULL`, and either way rules the database once enforced become application conventions that every program touching the database has to honour by hand. Critics read polymorphism as an ORM convenience imposed on a schema.
+
+The criticism does not make the need go away. Favourites lists, feeds, and attachments are mixed collections in reality, and a design that refuses polymorphism pays elsewhere, with a pivot table and an endpoint per type, union queries behind every mixed list, and the same feature built several times over. Neither side of the trade is free, so the question is which set of costs fits your data.
+
+Reach for STI when the types are **variations of one thing**. They share most of their columns, they appear together in the same lists and relationships, and things point at "any of them". Teams that are football, rugby, or cricket teams. Attachments that are images or videos. If you need one relationship that holds several of these types, STI fits.
+
+STI is also the only workable shape when **the types themselves are user data**. If users define their own kinds at runtime, there is no way to create a table or a model per kind upfront, while a discriminator column absorbs new values without a migration. See [Families discovered at runtime](#families-discovered-at-runtime) for how the resource side keeps up.
+
+The costs are real, and they are schema costs, so they outlive any library choice:
+
+- **Sparse columns.** Every subtype's columns exist on every row. A column only rugby teams use is `NULL` on every football team. The table gets wide, and `NOT NULL` stops being expressible for subtype-specific columns, the database cannot say "scrum_wins is required, but only for rugby teams" without check constraints keyed on the discriminator.
+- **The schema does not enforce the discriminator.** Nothing stops a query from treating a rugby row as a football team; the id space is shared, so any id "exists" for any subtype. Discipline has to live in the application layer, which is why this package verifies claimed types against the discriminator on writes.
+- **Everything shares the table.** Migrations, indexes, and locks affect the whole family. A busy subtype's traffic is every subtype's traffic.
+- **One relation cannot span the split.** If you later move a subtype out to its own table, every relation targeting the base breaks.
+
+If the types share little beyond a name, prefer separate tables and separate endpoints and no polymorphism at all. A relationship that must span genuinely different tables needs the type + id column pair, with the trade-offs above.
+
+---
+
+Next: [Links](./links.md) · [Errors & negotiation](./errors.md) · [Reference](./reference.md)
diff --git a/docs/reading-data.md b/docs/reading-data.md
index 5dde6f7..0829b1c 100644
--- a/docs/reading-data.md
+++ b/docs/reading-data.md
@@ -270,4 +270,4 @@ This is deliberately explicit and per-query. Visibility is a security concern, a
 
 ---
 
-Next: [Writing data](./writing-data.md) · [Links](./links.md) · [Errors & negotiation](./errors.md) · [Reference](./reference.md)
+Next: [Writing data](./writing-data.md) · [Polymorphism](./polymorphism.md) · [Links](./links.md) · [Errors & negotiation](./errors.md) · [Reference](./reference.md)
diff --git a/docs/writing-data.md b/docs/writing-data.md
index 7c70f35..2a84083 100644
--- a/docs/writing-data.md
+++ b/docs/writing-data.md
@@ -96,4 +96,4 @@ Register a subset of these routes with the `relationshipsOnly` option; see [Sele
 
 ---
 
-Next: [Links](./links.md) · [Errors & negotiation](./errors.md) · [Reference](./reference.md)
+Next: [Polymorphism](./polymorphism.md) · [Links](./links.md) · [Errors & negotiation](./errors.md) · [Reference](./reference.md)
diff --git a/examples/blog/.prettierignore b/examples/blog/.prettierignore
index 8e91c7d..c94e8e4 100644
--- a/examples/blog/.prettierignore
+++ b/examples/blog/.prettierignore
@@ -1,3 +1,5 @@
 .adonisjs
 node_modules
 build
+# Regenerated by node ace migration:run without formatting
+database/schema.ts
diff --git a/examples/blog/app/models/article.ts b/examples/blog/app/models/article.ts
index c684da5..63dadd8 100644
--- a/examples/blog/app/models/article.ts
+++ b/examples/blog/app/models/article.ts
@@ -4,6 +4,7 @@ import type { BelongsTo, HasMany, ManyToMany } from '@adonisjs/lucid/types/relat
 import User from '#models/user'
 import Comment from '#models/comment'
 import Tag from '#models/tag'
+import Attachment from '#models/attachment'
 
 export default class Article extends ArticleSchema {
   @belongsTo(() => User, { foreignKey: 'authorId' })
@@ -14,4 +15,11 @@ export default class Article extends ArticleSchema {
 
   @manyToMany(() => Tag, { pivotTable: 'article_tags' })
   declare tags: ManyToMany<typeof Tag>
+
+  @manyToMany(() => Attachment, { pivotTable: 'article_attachments' })
+  declare attachments: ManyToMany<typeof Attachment>
+
+  /** A belongsTo targeting the STI base: the cover is an image or a video. */
+  @belongsTo(() => Attachment, { foreignKey: 'coverAttachmentId' })
+  declare cover: BelongsTo<typeof Attachment>
 }
diff --git a/examples/blog/app/models/attachment.ts b/examples/blog/app/models/attachment.ts
new file mode 100644
index 0000000..9b31d5e
--- /dev/null
+++ b/examples/blog/app/models/attachment.ts
@@ -0,0 +1,47 @@
+import { AttachmentSchema } from '#database/schema'
+import { beforeCreate } from '@adonisjs/lucid/orm'
+import type { LucidModel, ModelAdapterOptions } from '@adonisjs/lucid/types/model'
+import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
+
+/**
+ * The base of a single-table inheritance family. Images and videos share
+ * the attachments table, told apart by the kind column. Application code
+ * uses the subclasses; relations that can hold either target this base,
+ * which stays unscoped so it sees the whole family.
+ */
+export default class Attachment extends AttachmentSchema {
+  /** The discriminator value each subclass owns; null on the base. */
+  static readonly attachmentKind: 'image' | 'video' | null = null
+
+  /**
+   * Scopes subclass queries to their discriminator, so Image.query()
+   * only ever sees image rows. find/findOrFail/first inherit the scope
+   * because they build on query().
+   */
+  static query<Model extends LucidModel, Result = InstanceType<Model>>(
+    this: Model,
+    options?: ModelAdapterOptions
+  ): ModelQueryBuilderContract<Model, Result> {
+    const query = super.query(options) as unknown as ModelQueryBuilderContract<Model, Result>
+    const kind = (this as unknown as typeof Attachment).attachmentKind
+    if (kind) query.where('kind', kind)
+    return query
+  }
+
+  /** Rows created through a subclass carry its discriminator. */
+  @beforeCreate()
+  static assignKind(row: Attachment) {
+    const kind = (row.constructor as typeof Attachment).attachmentKind
+    if (kind && !row.kind) row.kind = kind
+  }
+}
+
+export class Image extends Attachment {
+  static table = 'attachments'
+  static readonly attachmentKind = 'image' as const
+}
+
+export class Video extends Attachment {
+  static table = 'attachments'
+  static readonly attachmentKind = 'video' as const
+}
diff --git a/examples/blog/app/resources/attachment_resource.ts b/examples/blog/app/resources/attachment_resource.ts
new file mode 100644
index 0000000..b8087f4
--- /dev/null
+++ b/examples/blog/app/resources/attachment_resource.ts
@@ -0,0 +1,18 @@
+import Attachment from '#models/attachment'
+import ImageResource from '#resources/image_resource'
+import VideoResource from '#resources/video_resource'
+import { JsonApiResource } from '@evoactivity/jsonapi-adonis'
+
+/**
+ * The base resource of the STI family. resolveResource maps a row to its
+ * concrete resource by the discriminator; subtypes is the set of types a
+ * relation targeting Attachment accepts on writes. Registering this base
+ * registers both subtype resources with it.
+ */
+export default class AttachmentResource extends JsonApiResource<Attachment> {
+  static model = () => Attachment
+  static subtypes = () => [ImageResource, VideoResource]
+  static resolveResource(row: Attachment) {
+    return { image: ImageResource, video: VideoResource }[row.kind]
+  }
+}
diff --git a/examples/blog/app/resources/image_resource.ts b/examples/blog/app/resources/image_resource.ts
new file mode 100644
index 0000000..4f843df
--- /dev/null
+++ b/examples/blog/app/resources/image_resource.ts
@@ -0,0 +1,7 @@
+import { Image } from '#models/attachment'
+import { JsonApiResource } from '@evoactivity/jsonapi-adonis'
+
+export default class ImageResource extends JsonApiResource<Image> {
+  static type = 'images'
+  static model = () => Image
+}
diff --git a/examples/blog/app/resources/video_resource.ts b/examples/blog/app/resources/video_resource.ts
new file mode 100644
index 0000000..8fda945
--- /dev/null
+++ b/examples/blog/app/resources/video_resource.ts
@@ -0,0 +1,7 @@
+import { Video } from '#models/attachment'
+import { JsonApiResource } from '@evoactivity/jsonapi-adonis'
+
+export default class VideoResource extends JsonApiResource<Video> {
+  static type = 'videos'
+  static model = () => Video
+}
diff --git a/examples/blog/config/jsonapi.ts b/examples/blog/config/jsonapi.ts
index eeb066f..253afeb 100644
--- a/examples/blog/config/jsonapi.ts
+++ b/examples/blog/config/jsonapi.ts
@@ -8,6 +8,9 @@ export default defineConfig({
   resources: [
     () => import('#resources/article_resource'),
     () => import('#resources/user_resource'),
+    () => import('#resources/attachment_resource'),
+    () => import('#resources/image_resource'),
+    () => import('#resources/video_resource'),
   ],
 
   /**
diff --git a/examples/blog/database/migrations/1769000000004_create_attachments_table.ts b/examples/blog/database/migrations/1769000000004_create_attachments_table.ts
new file mode 100644
index 0000000..098bc02
--- /dev/null
+++ b/examples/blog/database/migrations/1769000000004_create_attachments_table.ts
@@ -0,0 +1,45 @@
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'attachments'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.increments('id').notNullable()
+      table.string('title').notNullable()
+      // Discriminator for the single-table inheritance family
+      table.string('kind').notNullable()
+      table.string('url').notNullable()
+
+      table.timestamp('created_at').notNullable()
+      table.timestamp('updated_at').nullable()
+    })
+
+    this.schema.createTable('article_attachments', (table) => {
+      table.increments('id').notNullable()
+      table
+        .integer('article_id')
+        .unsigned()
+        .notNullable()
+        .references('id')
+        .inTable('articles')
+        .onDelete('CASCADE')
+      table
+        .integer('attachment_id')
+        .unsigned()
+        .notNullable()
+        .references('id')
+        .inTable('attachments')
+        .onDelete('CASCADE')
+      table.unique(['article_id', 'attachment_id'])
+
+      table.timestamp('created_at').nullable()
+      table.timestamp('updated_at').nullable()
+    })
+  }
+
+  async down() {
+    this.schema.dropTable('article_attachments')
+    this.schema.dropTable(this.tableName)
+  }
+}
diff --git a/examples/blog/database/migrations/1769000000005_add_cover_to_articles.ts b/examples/blog/database/migrations/1769000000005_add_cover_to_articles.ts
new file mode 100644
index 0000000..0fa809a
--- /dev/null
+++ b/examples/blog/database/migrations/1769000000005_add_cover_to_articles.ts
@@ -0,0 +1,23 @@
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'articles'
+
+  async up() {
+    this.schema.alterTable(this.tableName, (table) => {
+      table
+        .integer('cover_attachment_id')
+        .unsigned()
+        .nullable()
+        .references('id')
+        .inTable('attachments')
+        .onDelete('SET NULL')
+    })
+  }
+
+  async down() {
+    this.schema.alterTable(this.tableName, (table) => {
+      table.dropColumn('cover_attachment_id')
+    })
+  }
+}
diff --git a/examples/blog/database/schema.ts b/examples/blog/database/schema.ts
index cb8d6d9..52f5161 100644
--- a/examples/blog/database/schema.ts
+++ b/examples/blog/database/schema.ts
@@ -7,6 +7,21 @@
 import { BaseModel, column } from '@adonisjs/lucid/orm'
 import { DateTime } from 'luxon'
 
+export class ArticleAttachmentSchema extends BaseModel {
+  static $columns = ['articleId', 'attachmentId', 'createdAt', 'id', 'updatedAt'] as const
+  $columns = ArticleAttachmentSchema.$columns
+  @column()
+  declare articleId: number
+  @column()
+  declare attachmentId: number
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime | null
+  @column({ isPrimary: true })
+  declare id: number
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime | null
+}
+
 export class ArticleTagSchema extends BaseModel {
   static $columns = ['articleId', 'createdAt', 'id', 'tagId', 'updatedAt'] as const
   $columns = ArticleTagSchema.$columns
@@ -23,12 +38,14 @@ export class ArticleTagSchema extends BaseModel {
 }
 
 export class ArticleSchema extends BaseModel {
-  static $columns = ['authorId', 'body', 'createdAt', 'id', 'title', 'updatedAt'] as const
+  static $columns = ['authorId', 'body', 'coverAttachmentId', 'createdAt', 'id', 'title', 'updatedAt'] as const
   $columns = ArticleSchema.$columns
   @column()
   declare authorId: number
   @column()
   declare body: string
+  @column()
+  declare coverAttachmentId: number | null
   @column.dateTime({ autoCreate: true })
   declare createdAt: DateTime
   @column({ isPrimary: true })
@@ -39,19 +56,25 @@ export class ArticleSchema extends BaseModel {
   declare updatedAt: DateTime | null
 }
 
+export class AttachmentSchema extends BaseModel {
+  static $columns = ['createdAt', 'id', 'kind', 'title', 'updatedAt', 'url'] as const
+  $columns = AttachmentSchema.$columns
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime
+  @column({ isPrimary: true })
+  declare id: number
+  @column()
+  declare kind: string
+  @column()
+  declare title: string
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime | null
+  @column()
+  declare url: string
+}
+
 export class AuthAccessTokenSchema extends BaseModel {
-  static $columns = [
-    'abilities',
-    'createdAt',
-    'expiresAt',
-    'hash',
-    'id',
-    'lastUsedAt',
-    'name',
-    'tokenableId',
-    'type',
-    'updatedAt',
-  ] as const
+  static $columns = ['abilities', 'createdAt', 'expiresAt', 'hash', 'id', 'lastUsedAt', 'name', 'tokenableId', 'type', 'updatedAt'] as const
   $columns = AuthAccessTokenSchema.$columns
   @column()
   declare abilities: string
@@ -76,15 +99,7 @@ export class AuthAccessTokenSchema extends BaseModel {
 }
 
 export class CommentSchema extends BaseModel {
-  static $columns = [
-    'articleId',
-    'authorId',
-    'body',
-    'createdAt',
-    'id',
-    'published',
-    'updatedAt',
-  ] as const
+  static $columns = ['articleId', 'authorId', 'body', 'createdAt', 'id', 'published', 'updatedAt'] as const
   $columns = CommentSchema.$columns
   @column()
   declare articleId: number
diff --git a/examples/blog/tests/functional/jsonapi_sti.spec.ts b/examples/blog/tests/functional/jsonapi_sti.spec.ts
new file mode 100644
index 0000000..6fc6e7f
--- /dev/null
+++ b/examples/blog/tests/functional/jsonapi_sti.spec.ts
@@ -0,0 +1,220 @@
+/**
+ * Single-table inheritance over HTTP (package issue #9). Images and
+ * videos share the attachments table; articles hold a mixed to-many of
+ * both. Documents must carry concrete types everywhere, writes must
+ * accept any family member, and a claimed type that contradicts the
+ * row's discriminator must 404, because the identifier names a resource
+ * that does not exist.
+ */
+import { test } from '@japa/runner'
+import testUtils from '@adonisjs/core/services/test_utils'
+import User from '#models/user'
+import Article from '#models/article'
+import { Image, Video } from '#models/attachment'
+
+const MEDIA_TYPE = 'application/vnd.api+json'
+
+async function seed() {
+  const alice = await User.create({
+    fullName: 'Alice Author',
+    email: 'alice@example.com',
+    password: 'secret123',
+  })
+  const article = await Article.create({
+    title: 'Illustrated article',
+    body: 'Body',
+    authorId: alice.id,
+  })
+  // Creating through the subclasses exercises the beforeCreate hook that
+  // assigns the discriminator.
+  const image = await Image.create({ title: 'Diagram', url: '/diagram.png' })
+  const video = await Video.create({ title: 'Walkthrough', url: '/walkthrough.mp4' })
+  return { alice, article, image, video }
+}
+
+test.group('STI reads over HTTP', (group) => {
+  group.each.setup(() => testUtils.db().withGlobalTransaction())
+
+  test('included attachments carry concrete types', async ({ client, assert }) => {
+    const { article, image, video } = await seed()
+    await article.related('attachments').attach([image.id, video.id])
+
+    const response = await client.get(`/api/v1/articles/${article.id}?include=attachments`)
+    response.assertStatus(200)
+    const doc = response.body() as any
+
+    const linkage = doc.data.relationships.attachments.data
+    assert.sameDeepMembers(linkage, [
+      { type: 'images', id: String(image.id) },
+      { type: 'videos', id: String(video.id) },
+    ])
+    assert.sameMembers(
+      (doc.included as any[]).map((resource) => resource.type),
+      ['images', 'videos']
+    )
+  })
+
+  test('the relationship endpoint serves concrete linkage', async ({ client, assert }) => {
+    const { article, image, video } = await seed()
+    await article.related('attachments').attach([image.id, video.id])
+
+    const response = await client.get(`/api/v1/articles/${article.id}/relationships/attachments`)
+    response.assertStatus(200)
+    assert.sameDeepMembers((response.body() as any).data, [
+      { type: 'images', id: String(image.id) },
+      { type: 'videos', id: String(video.id) },
+    ])
+  })
+})
+
+test.group('STI writes over HTTP', (group) => {
+  group.each.setup(() => testUtils.db().withGlobalTransaction())
+
+  test('a mixed family payload attaches through the relationship endpoint', async ({
+    client,
+    assert,
+  }) => {
+    const { article, image, video } = await seed()
+
+    const response = await client
+      .post(`/api/v1/articles/${article.id}/relationships/attachments`)
+      .header('content-type', MEDIA_TYPE)
+      .json({
+        data: [
+          { type: 'images', id: String(image.id) },
+          { type: 'videos', id: String(video.id) },
+        ],
+      })
+    response.assertStatus(200)
+
+    await article.load('attachments')
+    assert.sameMembers(
+      article.attachments.map((attachment) => attachment.id),
+      [image.id, video.id]
+    )
+  })
+
+  test('a type outside the family is a 409', async ({ client, assert }) => {
+    const { article, image } = await seed()
+
+    const response = await client
+      .post(`/api/v1/articles/${article.id}/relationships/attachments`)
+      .header('content-type', MEDIA_TYPE)
+      .json({ data: [{ type: 'tags', id: String(image.id) }] })
+
+    response.assertStatus(409)
+    const detail = (response.body() as any).errors[0].detail as string
+    assert.match(detail, /"images"/)
+    assert.match(detail, /"videos"/)
+  })
+
+  test('a claimed type contradicting the discriminator is a 404', async ({ client, assert }) => {
+    const { article, video } = await seed()
+
+    // video.id exists in the shared table, but as a video: images/<id>
+    // names a resource that does not exist
+    const response = await client
+      .post(`/api/v1/articles/${article.id}/relationships/attachments`)
+      .header('content-type', MEDIA_TYPE)
+      .json({ data: [{ type: 'images', id: String(video.id) }] })
+
+    response.assertStatus(404)
+
+    await article.load('attachments')
+    assert.lengthOf(article.attachments, 0)
+  })
+
+  test('a resource create accepts family members in its relationships', async ({
+    client,
+    assert,
+  }) => {
+    const { alice, image, video } = await seed()
+
+    const response = await client.post('/api/v1/articles').json({
+      data: {
+        type: 'articles',
+        attributes: { title: 'With media', body: '...' },
+        relationships: {
+          author: { data: { type: 'users', id: String(alice.id) } },
+          attachments: {
+            data: [
+              { type: 'images', id: String(image.id) },
+              { type: 'videos', id: String(video.id) },
+            ],
+          },
+        },
+      },
+    })
+    response.assertStatus(201)
+
+    const created = await Article.findOrFail((response.body() as any).data.id)
+    await created.load('attachments')
+    assert.lengthOf(created.attachments, 2)
+  })
+
+  test('a resource create claiming the wrong subtype is a 404', async ({ client }) => {
+    const { alice, video } = await seed()
+
+    const response = await client.post('/api/v1/articles').json({
+      data: {
+        type: 'articles',
+        attributes: { title: 'Mislabelled', body: '...' },
+        relationships: {
+          author: { data: { type: 'users', id: String(alice.id) } },
+          attachments: { data: [{ type: 'images', id: String(video.id) }] },
+        },
+      },
+    })
+    response.assertStatus(404)
+  })
+})
+
+test.group('STI belongsTo over HTTP', (group) => {
+  group.each.setup(() => testUtils.db().withGlobalTransaction())
+
+  test('an unloaded belongsTo to the base serves links without data', async ({
+    client,
+    assert,
+  }) => {
+    const { article, image } = await seed()
+    article.coverAttachmentId = image.id
+    await article.save()
+
+    const response = await client.get(`/api/v1/articles/${article.id}`)
+    response.assertStatus(200)
+    const cover = (response.body() as any).data.relationships.cover
+    assert.isUndefined(cover.data)
+    assert.isDefined(cover.links.related)
+  })
+
+  test('replace accepts a family member and sets the foreign key', async ({ client, assert }) => {
+    const { article, video } = await seed()
+
+    const response = await client
+      .patch(`/api/v1/articles/${article.id}/relationships/cover`)
+      .header('content-type', MEDIA_TYPE)
+      .json({ data: { type: 'videos', id: String(video.id) } })
+    response.assertStatus(200)
+
+    await article.refresh()
+    assert.equal(article.coverAttachmentId, video.id)
+  })
+
+  test('replace with a mismatched claimed type is a 404 and sets nothing', async ({
+    client,
+    assert,
+  }) => {
+    const { article, video } = await seed()
+
+    // video.id exists in the shared table, but as a video: images/<id>
+    // names a resource that does not exist
+    const response = await client
+      .patch(`/api/v1/articles/${article.id}/relationships/cover`)
+      .header('content-type', MEDIA_TYPE)
+      .json({ data: { type: 'images', id: String(video.id) } })
+    response.assertStatus(404)
+
+    await article.refresh()
+    assert.isNull(article.coverAttachmentId)
+  })
+})
diff --git a/src/context.ts b/src/context.ts
index 3da3d69..6b4d6fb 100644
--- a/src/context.ts
+++ b/src/context.ts
@@ -178,13 +178,14 @@ export class JsonApiRequestContext {
    */
   async deserialize(
     model: LucidModel,
-    options: { expectedId?: string } = {}
+    options: { expectedId?: string; expectedType?: string } = {}
   ): Promise<DeserializedResource> {
     const result = deserializeResourceDocument(model, this.#registry, this.#ctx.request.body(), {
       expectedId: options.expectedId,
+      expectedType: options.expectedType,
       allowClientIds: this.#config.allowClientIds,
     })
-    await verifyRelatedExist(model, result.references)
+    await verifyRelatedExist(model, result.references, this.#registry)
     return result
   }
 
@@ -212,8 +213,7 @@ export class JsonApiRequestContext {
    */
   async renderRelationship(row: LucidRow, name: string): Promise<Document> {
     const linkage = await fetchLinkage(row, name, this.#registry)
-    const Model = row.constructor as LucidModel
-    const type = this.#registry.typeFor(Model)
+    const type = this.#registry.typeForRow(row)
     const id = String(row.$primaryKeyValue)
 
     const document: Document = { jsonapi: { version: JSON_API_VERSION }, data: linkage }
diff --git a/src/deserializer.ts b/src/deserializer.ts
index 6c85c83..f09bc76 100644
--- a/src/deserializer.ts
+++ b/src/deserializer.ts
@@ -1,9 +1,20 @@
 import type { LucidModel } from '@adonisjs/lucid/types/model'
-import { JsonApiException } from './errors.ts'
+import { JsonApiException, formatTypeList } from './errors.ts'
 import { isRelationExposed } from './resource.ts'
 import type { ResourceIdentifier } from './types.ts'
 import type { JsonApiRegistry } from './registry.ts'
 
+/**
+ * A relationship write's references to existing rows. claims carries the
+ * identifiers as the client sent them, so verifyRelatedExist can check a
+ * claimed type against the row it names.
+ */
+export type RelatedReference = {
+  relation: string
+  ids: string[]
+  claims?: ResourceIdentifier[]
+}
+
 /**
  * Result of deserializing a JSON:API resource document into Lucid-friendly
  * shapes:
@@ -14,16 +25,32 @@ import type { JsonApiRegistry } from './registry.ts'
  */
 export type DeserializedResource = {
   id?: string
+  /**
+   * The type the client sent as data.type, already validated against the
+   * accepted set. For an STI base endpoint this says which family member
+   * the document described, so the caller can stamp the discriminator.
+   */
+  type: string
   attributes: Record<string, unknown>
   toMany: Record<string, string[]>
   /**
    * Every related resource referenced by the document (to-one and to-many),
    * for existence verification (404 per spec).
    */
-  references: { relation: string; ids: string[] }[]
+  references: RelatedReference[]
 }
 
 export type DeserializeOptions = {
+  /**
+   * Narrows the accepted primary type to exactly this string. For an
+   * endpoint whose URL names one member of an STI family
+   * (/api/v1/:type), pass the type the URL names, so a body claiming a
+   * different family member is a 409. Without it, an STI base model
+   * accepts any member of its declared family, and any other model
+   * accepts its single type.
+   */
+  expectedType?: string
+
   /**
    * The id from the endpoint URL. When set (PATCH), data.id must be present
    * and match (400/409). When unset (POST), a client-generated id is
@@ -68,7 +95,9 @@ export function deserializeResourceDocument(
   body: unknown,
   options: DeserializeOptions = {}
 ): DeserializedResource {
-  const expectedType = registry.typeFor(Model)
+  const acceptedTypes = options.expectedType
+    ? [options.expectedType]
+    : registry.acceptedTypesFor(Model)
 
   if (!isPlainObject(body) || !('data' in body)) {
     throw invalidDocument('The request body must be an object with a "data" member', '')
@@ -80,9 +109,9 @@ export function deserializeResourceDocument(
   if (typeof data.type !== 'string') {
     throw invalidDocument('The resource object must have a string "type" member', '/data/type')
   }
-  if (data.type !== expectedType) {
+  if (!acceptedTypes.includes(data.type)) {
     throw conflict(
-      `Resource type "${data.type}" is not supported by this endpoint (expected "${expectedType}")`,
+      `Resource type "${data.type}" is not supported by this endpoint (expected ${formatTypeList(acceptedTypes)})`,
       '/data/type'
     )
   }
@@ -124,7 +153,7 @@ export function deserializeResourceDocument(
     attributes
   )
 
-  return { id, attributes, toMany, references }
+  return { id, type: data.type, attributes, toMany, references }
 }
 
 /**
@@ -164,9 +193,9 @@ function deserializeRelationships(
   registry: JsonApiRegistry,
   raw: unknown,
   attributes: Record<string, unknown>
-): { toMany: Record<string, string[]>; references: { relation: string; ids: string[] }[] } {
+): { toMany: Record<string, string[]>; references: RelatedReference[] } {
   const toMany: Record<string, string[]> = {}
-  const references: { relation: string; ids: string[] }[] = []
+  const references: RelatedReference[] = []
   if (raw === undefined) return { toMany, references }
   if (!isPlainObject(raw)) {
     throw invalidDocument('The "relationships" member must be an object', '/data/relationships')
@@ -187,7 +216,7 @@ function deserializeRelationships(
       )
     }
     relation.boot()
-    const relatedType = registry.typeFor(relation.relatedModel())
+    const acceptedTypes = registry.acceptedTypesFor(relation.relatedModel())
     const linkage = value.data
 
     if (relation.type === 'belongsTo') {
@@ -197,14 +226,14 @@ function deserializeRelationships(
         continue
       }
       const identifier = parseIdentifier(linkage, `${pointer}/data`)
-      if (identifier.type !== relatedType) {
+      if (!acceptedTypes.includes(identifier.type)) {
         throw conflict(
-          `Relationship "${name}" expects resources of type "${relatedType}"`,
+          `Relationship "${name}" expects resources of type ${formatTypeList(acceptedTypes)}`,
           `${pointer}/data/type`
         )
       }
       attributes[foreignKey] = identifier.id
-      references.push({ relation: name, ids: [identifier.id] })
+      references.push({ relation: name, ids: [identifier.id], claims: [identifier] })
     } else if (relation.type === 'manyToMany' || relation.type === 'hasMany') {
       if (!Array.isArray(linkage)) {
         throw invalidDocument(
@@ -212,17 +241,18 @@ function deserializeRelationships(
           `${pointer}/data`
         )
       }
-      toMany[name] = linkage.map((entry, index) => {
+      const identifiers = linkage.map((entry, index) => {
         const identifier = parseIdentifier(entry, `${pointer}/data/${index}`)
-        if (identifier.type !== relatedType) {
+        if (!acceptedTypes.includes(identifier.type)) {
           throw conflict(
-            `Relationship "${name}" expects resources of type "${relatedType}"`,
+            `Relationship "${name}" expects resources of type ${formatTypeList(acceptedTypes)}`,
             `${pointer}/data/${index}/type`
           )
         }
-        return identifier.id
+        return identifier
       })
-      references.push({ relation: name, ids: toMany[name] })
+      toMany[name] = identifiers.map((identifier) => identifier.id)
+      references.push({ relation: name, ids: toMany[name], claims: identifiers })
     } else {
       throw new JsonApiException(
         {
@@ -244,9 +274,10 @@ function deserializeRelationships(
  */
 export async function verifyRelatedExist(
   Model: LucidModel,
-  references: { relation: string; ids: string[] }[]
+  references: RelatedReference[],
+  registry: JsonApiRegistry
 ): Promise<void> {
-  for (const { relation: name, ids } of references) {
+  for (const { relation: name, ids, claims } of references) {
     if (ids.length === 0) continue
     const relation = Model.$relationsDefinitions.get(name)!
     relation.boot()
@@ -264,5 +295,29 @@ export async function verifyRelatedExist(
         { status: 404 }
       )
     }
+
+    // For an STI family, an identifier's type is part of the identity: a
+    // claimed type the row's discriminator contradicts names a resource
+    // that does not exist, same as an unknown id. Without this check the
+    // shared id space would let a mislabelled identifier attach silently.
+    if (claims?.length && registry.resourceFor(RelatedModel).subtypes) {
+      const byId = new Map(rows.map((row) => [String(row.$primaryKeyValue), row]))
+      const wrong = claims.filter((claim) => {
+        const row = byId.get(claim.id)
+        return row !== undefined && registry.typeForRow(row) !== claim.type
+      })
+      if (wrong.length) {
+        throw new JsonApiException(
+          {
+            title: 'Not Found',
+            detail: `Related resources do not exist: ${wrong
+              .map((claim) => `${claim.type}/${claim.id}`)
+              .join(', ')}`,
+            source: { pointer: `/data/relationships/${name}` },
+          },
+          { status: 404 }
+        )
+      }
+    }
   }
 }
diff --git a/src/document_builder.ts b/src/document_builder.ts
index 70df8aa..f4e8868 100644
--- a/src/document_builder.ts
+++ b/src/document_builder.ts
@@ -111,7 +111,7 @@ export class DocumentBuilder {
     const Model = row.constructor as LucidModel
     const ResourceClass = this.#registry.resourceForRow(row)
     const definition = instantiateResource(ResourceClass, row, this.#ctx)
-    const type = this.#registry.typeFor(Model)
+    const type = this.#registry.typeForRow(row)
     const id = definition.id()
     const allowedFields = this.#params.fields[type]
 
@@ -168,14 +168,20 @@ export class DocumentBuilder {
         relationship.data = this.#linkage(preloaded, subInclude)
       } else if (relation.type === 'belongsTo') {
         // Resource linkage for an unloaded belongsTo is derivable from the
-        // foreign key without touching the database.
+        // foreign key without touching the database. Not when the target is
+        // an STI base (its resource declares subtypes): a bare foreign key
+        // cannot name a concrete type, and guessing the base type creates a
+        // second identity for the same row. The member keeps its links and
+        // omits data; loading the relation gives concrete linkage.
         relation.boot()
-        const foreignKey = (relation as unknown as { foreignKey: string }).foreignKey
-        const value = getAttribute(row, foreignKey)
-        relationship.data =
-          typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint'
-            ? { type: this.#registry.typeFor(relation.relatedModel()), id: String(value) }
-            : null
+        if (!this.#registry.resourceFor(relation.relatedModel()).subtypes) {
+          const foreignKey = (relation as unknown as { foreignKey: string }).foreignKey
+          const value = getAttribute(row, foreignKey)
+          relationship.data =
+            typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint'
+              ? { type: this.#registry.typeFor(relation.relatedModel()), id: String(value) }
+              : null
+        }
       }
 
       const links = this.#links.relationshipLinks(context.type, context.id, serializedName)
@@ -198,17 +204,16 @@ export class DocumentBuilder {
 
     const identify = (related: LucidRow): ResourceIdentifier => {
       if (subInclude) this.#visitIncluded(related, subInclude)
-      const RelatedModel = related.constructor as LucidModel
       const ResourceClass = this.#registry.resourceForRow(related)
       const definition = instantiateResource(ResourceClass, related, this.#ctx)
-      return { type: this.#registry.typeFor(RelatedModel), id: definition.id() }
+      return { type: this.#registry.typeForRow(related), id: definition.id() }
     }
 
     return Array.isArray(preloaded) ? preloaded.map(identify) : identify(preloaded)
   }
 
   #visitIncluded(row: LucidRow, include: IncludeTree) {
-    const type = this.#registry.typeFor(row.constructor as LucidModel)
+    const type = this.#registry.typeForRow(row)
     const ResourceClass = this.#registry.resourceForRow(row)
     const id = instantiateResource(ResourceClass, row, this.#ctx).id()
     const key = `${type}:${id}`
diff --git a/src/errors.ts b/src/errors.ts
index dae86f9..cf4a1a6 100644
--- a/src/errors.ts
+++ b/src/errors.ts
@@ -7,6 +7,13 @@ import { JSON_API_MEDIA_TYPE, JSON_API_VERSION, type Document, type ErrorObject
  * itself (invalid include paths, unknown sort fields, ...) and available
  * to userland for custom errors.
  */
+/**
+ * Formats acceptable JSON:API types for an error detail: '"a" or "b"'.
+ */
+export function formatTypeList(types: string[]): string {
+  return types.map((type) => `"${type}"`).join(' or ')
+}
+
 export class JsonApiException extends Exception {
   static status = 400
   static code = 'E_JSON_API_ERROR'
diff --git a/src/registry.ts b/src/registry.ts
index efbe3fe..5813695 100644
--- a/src/registry.ts
+++ b/src/registry.ts
@@ -1,10 +1,9 @@
-import string from '@adonisjs/core/helpers/string'
 import type { LucidModel, LucidRow } from '@adonisjs/lucid/types/model'
 import { JsonApiResource } from './resource.ts'
 
 export type JsonApiResourceClass = Pick<
   typeof JsonApiResource,
-  'type' | 'model' | 'exposeRelationships' | 'filters'
+  'type' | 'model' | 'exposeRelationships' | 'filters' | 'subtypes' | 'resolveResource' | 'typeName'
 > & {
   /**
    * `never` parameters keep subclass constructors (which narrow the row and
@@ -34,7 +33,7 @@ export function instantiateResource(
  */
 export class JsonApiRegistry {
   #byModel = new Map<LucidModel, JsonApiResourceClass>()
-  #typeByModel = new Map<LucidModel, string>()
+  #typeByResource = new Map<JsonApiResourceClass, string>()
 
   register(resources: JsonApiResourceClass[]) {
     for (const resource of resources) {
@@ -42,6 +41,16 @@ export class JsonApiRegistry {
         throw new Error(`JSON:API resource "${resource.name}" must define a static model property`)
       }
       this.#byModel.set(resource.model(), resource)
+
+      // A base resource registers its declared family, so one import line
+      // covers an STI family. Explicit registrations win, so a subtype
+      // whose model already has a resource is left alone, which also
+      // bounds the recursion.
+      for (const subtype of resource.subtypes?.() ?? []) {
+        if (subtype.model && !this.#byModel.has(subtype.model())) {
+          this.register([subtype])
+        }
+      }
     }
     return this
   }
@@ -52,13 +61,7 @@ export class JsonApiRegistry {
    * in type values per the spec's member-name character rules.
    */
   typeFor(Model: LucidModel): string {
-    const cached = this.#typeByModel.get(Model)
-    if (cached) return cached
-
-    const resource = this.#byModel.get(Model)
-    const type = resource?.type ?? string.dashCase(Model.table)
-    this.#typeByModel.set(Model, type)
-    return type
+    return this.#typeOf(this.resourceFor(Model))
   }
 
   /**
@@ -67,13 +70,62 @@ export class JsonApiRegistry {
   resourceFor(Model: LucidModel): JsonApiResourceClass {
     let resource = this.#byModel.get(Model)
     if (!resource) {
-      resource = class extends JsonApiResource {}
+      resource = class extends JsonApiResource {
+        static model = () => Model
+      }
       this.#byModel.set(Model, resource)
     }
     return resource
   }
 
+  /**
+   * The resource class for a row, resolving through resolveResource when
+   * the row's resource declares one (single-table inheritance). Hooks can
+   * chain; a repeated class ends the walk so a cycle cannot loop.
+   */
   resourceForRow(row: LucidRow): JsonApiResourceClass {
-    return this.resourceFor(row.constructor as LucidModel)
+    let resource = this.resourceFor(row.constructor as LucidModel)
+    const visited = new Set<JsonApiResourceClass>([resource])
+
+    while (resource.resolveResource) {
+      const resolved = resource.resolveResource(row as never)
+      if (!resolved || visited.has(resolved)) break
+      visited.add(resolved)
+      resource = resolved
+    }
+    return resource
+  }
+
+  /**
+   * The JSON:API type string for a row. Differs from typeFor(Model) only
+   * when the row's resource resolves to a concrete subtype resource.
+   */
+  typeForRow(row: LucidRow): string {
+    return this.#typeOf(this.resourceForRow(row))
+  }
+
+  /**
+   * The types a relation targeting this model accepts on writes. A model
+   * whose resource declares subtypes accepts every member of the family
+   * and nothing else. The base's own abstract type never appears in
+   * payloads. Every other model accepts its single type, as before.
+   */
+  acceptedTypesFor(Model: LucidModel): string[] {
+    const subtypes = this.resourceFor(Model).subtypes?.()
+    if (!subtypes) return [this.typeFor(Model)]
+    return subtypes.map((subtype) => this.#typeOf(subtype))
+  }
+
+  /**
+   * Every type string comes from resource.typeName(), cached per resource
+   * class because row serialization is a hot path.
+   */
+  #typeOf(resource: JsonApiResourceClass): string {
+    let type = this.#typeByResource.get(resource)
+    if (!type) {
+      type = resource.typeName()
+      this.#typeByResource.set(resource, type)
+    }
+    return type
   }
 }
diff --git a/src/relationships.ts b/src/relationships.ts
index 50aadb1..dff187f 100644
--- a/src/relationships.ts
+++ b/src/relationships.ts
@@ -1,7 +1,7 @@
 import string from '@adonisjs/core/helpers/string'
 import type { LucidModel, LucidRow } from '@adonisjs/lucid/types/model'
 import { loadRelation, relatedClient, setAttribute } from './lucid_access.ts'
-import { JsonApiException } from './errors.ts'
+import { JsonApiException, formatTypeList } from './errors.ts'
 import { verifyRelatedExist } from './deserializer.ts'
 import { isRelationExposed } from './resource.ts'
 import type { JsonApiRegistry } from './registry.ts'
@@ -50,7 +50,7 @@ export function getRelationOrFail(Model: LucidModel, name: string, registry: Jso
  */
 function parseLinkage(
   body: unknown,
-  relatedType: string,
+  acceptedTypes: string[],
   cardinality: 'to-one' | 'to-many'
 ): ResourceIdentifier[] | null {
   if (!isPlainObject(body) || !('data' in body)) {
@@ -62,11 +62,11 @@ function parseLinkage(
     if (!isPlainObject(value) || typeof value.type !== 'string' || typeof value.id !== 'string') {
       throw invalidLinkage('Resource identifier objects must have string "type" and "id"')
     }
-    if (value.type !== relatedType) {
+    if (!acceptedTypes.includes(value.type)) {
       throw new JsonApiException(
         {
           title: 'Conflict',
-          detail: `This relationship holds resources of type "${relatedType}"`,
+          detail: `This relationship holds resources of type ${formatTypeList(acceptedTypes)}`,
           source: { pointer: '/data' },
         },
         { status: 409 }
@@ -99,7 +99,7 @@ export async function updateRelationship(
   const Model = row.constructor as LucidModel
   const relation = getRelationOrFail(Model, name, registry)
   const relationName = relation.relationName
-  const relatedType = registry.typeFor(relation.relatedModel())
+  const acceptedTypes = registry.acceptedTypesFor(relation.relatedModel())
 
   if (relation.type === 'belongsTo') {
     if (action !== 'replace') {
@@ -108,12 +108,16 @@ export async function updateRelationship(
         { status: 405 }
       )
     }
-    const identifiers = parseLinkage(body, relatedType, 'to-one')
+    const identifiers = parseLinkage(body, acceptedTypes, 'to-one')
     const foreignKey = (relation as unknown as { foreignKey: string }).foreignKey
     if (identifiers === null) {
       setAttribute(row, foreignKey, null)
     } else {
-      await verifyRelatedExist(Model, [{ relation: relationName, ids: [identifiers[0].id] }])
+      await verifyRelatedExist(
+        Model,
+        [{ relation: relationName, ids: [identifiers[0].id], claims: identifiers }],
+        registry
+      )
       setAttribute(row, foreignKey, identifiers[0].id)
     }
     await row.save()
@@ -121,9 +125,13 @@ export async function updateRelationship(
   }
 
   if (relation.type === 'manyToMany') {
-    const identifiers = parseLinkage(body, relatedType, 'to-many')!
+    const identifiers = parseLinkage(body, acceptedTypes, 'to-many')!
     const ids = identifiers.map((identifier) => identifier.id)
-    await verifyRelatedExist(Model, [{ relation: relationName, ids }])
+    await verifyRelatedExist(
+      Model,
+      [{ relation: relationName, ids, claims: identifiers }],
+      registry
+    )
     const related = relatedClient(row, relationName)
 
     if (action === 'replace') {
@@ -148,9 +156,13 @@ export async function updateRelationship(
         { status: 403 }
       )
     }
-    const identifiers = parseLinkage(body, relatedType, 'to-many')!
+    const identifiers = parseLinkage(body, acceptedTypes, 'to-many')!
     const ids = identifiers.map((identifier) => identifier.id)
-    await verifyRelatedExist(Model, [{ relation: relationName, ids }])
+    await verifyRelatedExist(
+      Model,
+      [{ relation: relationName, ids, claims: identifiers }],
+      registry
+    )
     const RelatedModel = relation.relatedModel()
     const children = await RelatedModel.query().whereIn(RelatedModel.primaryKey, ids)
     await relatedClient(row, relationName).saveMany(children)
@@ -178,7 +190,7 @@ export async function fetchLinkage(
   const loaded = row.$preloaded[relationName] as LucidRow | LucidRow[] | null | undefined
 
   const identify = (related: LucidRow): ResourceIdentifier => ({
-    type: registry.typeFor(related.constructor as LucidModel),
+    type: registry.typeForRow(related),
     id: String(related.$primaryKeyValue),
   })
 
diff --git a/src/resource.ts b/src/resource.ts
index d3c5b46..308c557 100644
--- a/src/resource.ts
+++ b/src/resource.ts
@@ -1,7 +1,9 @@
+import string from '@adonisjs/core/helpers/string'
 import type { HttpContext } from '@adonisjs/core/http'
 import type { LucidModel, LucidRow } from '@adonisjs/lucid/types/model'
 import type { Links, Meta } from './types.ts'
 import type { FilterHandler } from './filters.ts'
+import type { JsonApiResourceClass } from './registry.ts'
 
 /**
  * Describes how a Lucid model serializes into a JSON:API resource object.
@@ -43,6 +45,23 @@ export class JsonApiResource<Row extends LucidRow = LucidRow> {
    */
   declare static type?: string
 
+  /**
+   * The JSON:API type this resource serializes as. This is the single
+   * home for type derivation, consulted by the registry for models and
+   * rows alike. Override it to compute types under a different scheme
+   * entirely.
+   */
+  static typeName(this: JsonApiResourceClass): string {
+    if (this.type) return this.type
+    const Model = this.model?.()
+    if (!Model) {
+      throw new Error(
+        `JSON:API resource "${this.name}" must declare a static type or model to derive its type`
+      )
+    }
+    return string.dashCase(Model.table)
+  }
+
   /**
    * The Lucid model this resource describes. Required when registering the
    * resource explicitly.
@@ -62,6 +81,24 @@ export class JsonApiResource<Row extends LucidRow = LucidRow> {
    */
   declare static filters?: Record<string, FilterHandler>
 
+  /**
+   * For the base resource of a single-table inheritance family, the
+   * concrete resources rows of this model can serialize as. Declaring this
+   * makes relations targeting the base accept any member type on writes,
+   * and switches unloaded belongsTo linkage to links-only (the concrete
+   * type of an unloaded row is unknowable from a bare foreign key).
+   */
+  declare static subtypes?: () => JsonApiResourceClass[]
+
+  /**
+   * For the base resource of a single-table inheritance family, maps a row
+   * to its concrete resource, typically by reading the discriminator
+   * column. Returning undefined keeps the row on this resource. Consulted
+   * by the registry wherever a row is serialized, so linkage and included
+   * documents carry concrete types.
+   */
+  declare static resolveResource?: (row: never) => JsonApiResourceClass | undefined
+
   constructor(
     protected resource: Row,
     protected ctx?: HttpContext
diff --git a/tests/fixtures/models.ts b/tests/fixtures/models.ts
index 0942f43..a56f13e 100644
--- a/tests/fixtures/models.ts
+++ b/tests/fixtures/models.ts
@@ -136,3 +136,57 @@ export function make<T extends typeof BaseModel>(
   Object.assign(row, attributes)
   return row
 }
+
+/**
+ * Single-table inheritance family for polymorphism tests. SportsTeam is
+ * the base, FootballTeam and RugbyTeam are subclasses over the same
+ * table, sport is the discriminator. This is the pattern the polymorphism
+ * feature exists for (issue #9).
+ */
+export class SportsTeam extends BaseModel {
+  static table = 'sports_teams'
+
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare name: string
+
+  @column()
+  declare sport: 'football' | 'rugby'
+}
+
+export class FootballTeam extends SportsTeam {
+  static table = 'sports_teams'
+}
+
+export class RugbyTeam extends SportsTeam {
+  static table = 'sports_teams'
+}
+
+/** A belongsTo targeting the STI base. */
+export class Stadium extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare name: string
+
+  @column()
+  declare teamId: number
+
+  @belongsTo(() => SportsTeam, { foreignKey: 'teamId' })
+  declare team: BelongsTo<typeof SportsTeam>
+}
+
+/** A manyToMany targeting the STI base. */
+export class Fan extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare name: string
+
+  @manyToMany(() => SportsTeam, { pivotTable: 'favourites' })
+  declare favourites: ManyToMany<typeof SportsTeam>
+}
diff --git a/tests/fixtures/sti_resources.ts b/tests/fixtures/sti_resources.ts
new file mode 100644
index 0000000..1a44795
--- /dev/null
+++ b/tests/fixtures/sti_resources.ts
@@ -0,0 +1,33 @@
+/**
+ * The resource family for the SportsTeam STI fixtures, shared by the STI
+ * spec files the way models.ts is shared.
+ */
+import { JsonApiRegistry } from '../../src/registry.ts'
+import { JsonApiResource } from '../../src/resource.ts'
+import { FootballTeam, RugbyTeam, SportsTeam } from './models.ts'
+
+export class FootballTeamResource extends JsonApiResource<FootballTeam> {
+  static type = 'football-teams'
+  static model = () => FootballTeam
+}
+
+export class RugbyTeamResource extends JsonApiResource<RugbyTeam> {
+  static type = 'rugby-teams'
+  static model = () => RugbyTeam
+}
+
+export class SportsTeamResource extends JsonApiResource<SportsTeam> {
+  static model = () => SportsTeam
+  static subtypes = () => [FootballTeamResource, RugbyTeamResource]
+  static resolveResource(row: SportsTeam) {
+    return { football: FootballTeamResource, rugby: RugbyTeamResource }[row.sport]
+  }
+}
+
+export function stiRegistry() {
+  return new JsonApiRegistry().register([
+    SportsTeamResource,
+    FootballTeamResource,
+    RugbyTeamResource,
+  ])
+}
diff --git a/tests/unit/deserializer.spec.ts b/tests/unit/deserializer.spec.ts
index dfe5911..01c2f7d 100644
--- a/tests/unit/deserializer.spec.ts
+++ b/tests/unit/deserializer.spec.ts
@@ -44,8 +44,15 @@ test.group('deserializeResourceDocument: structure', () => {
     assert.deepEqual(result.attributes, { title: 'Hello', authorId: '7' })
     assert.deepEqual(result.toMany, { tags: ['1', '2'] })
     assert.deepEqual(result.references, [
-      { relation: 'author', ids: ['7'] },
-      { relation: 'tags', ids: ['1', '2'] },
+      { relation: 'author', ids: ['7'], claims: [{ type: 'users', id: '7' }] },
+      {
+        relation: 'tags',
+        ids: ['1', '2'],
+        claims: [
+          { type: 'tags', id: '1' },
+          { type: 'tags', id: '2' },
+        ],
+      },
     ])
   })
 
diff --git a/tests/unit/sti_documents.spec.ts b/tests/unit/sti_documents.spec.ts
new file mode 100644
index 0000000..0235103
--- /dev/null
+++ b/tests/unit/sti_documents.spec.ts
@@ -0,0 +1,140 @@
+/**
+ * Documents carry concrete types for STI rows (issue #9). Loaded rows
+ * resolve through resolveResource wherever they appear, as primary data,
+ * in linkage, and in included. An unloaded belongsTo targeting an STI
+ * base emits no data member at all, because a bare foreign key cannot
+ * name a concrete type; guessing produced a second identity for the same
+ * row and a full-linkage violation.
+ */
+import { test } from '@japa/runner'
+import { DocumentBuilder } from '../../src/document_builder.ts'
+import { JsonApiRegistry } from '../../src/registry.ts'
+import { JsonApiResource } from '../../src/resource.ts'
+import { LinkBuilder } from '../../src/links.ts'
+import { parseQueryParams } from '../../src/params.ts'
+import { Fan, SportsTeam, Stadium, make } from '../fixtures/models.ts'
+import { stiRegistry as registry } from '../fixtures/sti_resources.ts'
+import { stubRouter } from '../fixtures/stub_router.ts'
+
+function build(input: any, qs: Record<string, unknown> = {}, reg = registry()) {
+  return new DocumentBuilder(reg, parseQueryParams(qs), new LinkBuilder(false)).build(input)
+}
+
+test.group('STI documents: primary data', () => {
+  test('a base-hydrated row serializes under its concrete type', ({ assert }) => {
+    const doc = build(make(SportsTeam, { name: 'Arsenal', sport: 'football' }))
+    assert.equal((doc.data as any).type, 'football-teams')
+  })
+
+  test('a mixed collection carries one concrete type per row', ({ assert }) => {
+    const doc = build([
+      make(SportsTeam, { name: 'Arsenal', sport: 'football' }),
+      make(SportsTeam, { name: 'Saracens', sport: 'rugby' }),
+    ])
+    assert.deepEqual(
+      (doc.data as any[]).map((resource) => resource.type),
+      ['football-teams', 'rugby-teams']
+    )
+  })
+
+  test('sparse fieldsets key on the concrete type', ({ assert }) => {
+    const doc = build(make(SportsTeam, { name: 'Arsenal', sport: 'football' }), {
+      fields: { 'football-teams': 'name' },
+    })
+    assert.deepEqual(Object.keys((doc.data as any).attributes), ['name'])
+  })
+
+  test('the abstract type is inert as a fieldset key', ({ assert }) => {
+    const doc = build(make(SportsTeam, { name: 'Arsenal', sport: 'football' }), {
+      fields: { 'sports-teams': 'name' },
+    })
+    // the row is football-teams, so a sports-teams fieldset matches nothing
+    // and no filtering happens
+    assert.includeMembers(Object.keys((doc.data as any).attributes), ['name', 'sport'])
+  })
+})
+
+test.group('STI documents: linkage and included', () => {
+  test('to-many linkage carries the concrete type per row', ({ assert }) => {
+    const fan = make(Fan, { name: 'Liam' })
+    fan.$setRelated('favourites', [
+      make(SportsTeam, { name: 'Arsenal', sport: 'football' }),
+      make(SportsTeam, { name: 'Saracens', sport: 'rugby' }),
+    ])
+
+    const doc = build(fan)
+    const linkage = (doc.data as any).relationships.favourites.data
+    assert.deepEqual(
+      linkage.map((identifier: any) => identifier.type),
+      ['football-teams', 'rugby-teams']
+    )
+  })
+
+  test('included resources carry concrete types and dedupe under them', ({ assert }) => {
+    const fan = make(Fan, { name: 'Liam' })
+    const team = make(SportsTeam, { name: 'Arsenal', sport: 'football' })
+    fan.$setRelated('favourites', [team])
+
+    const doc = build(fan, { include: 'favourites' })
+    const included = doc.included as any[]
+    assert.equal(included.length, 1)
+    assert.equal(included[0].type, 'football-teams')
+    assert.equal(included[0].attributes.name, 'Arsenal')
+  })
+
+  test('a loaded belongsTo to the base gives concrete linkage', ({ assert }) => {
+    const stadium = make(Stadium, { name: 'Emirates', teamId: 5 })
+    stadium.$setRelated('team', make(SportsTeam, { id: 5, name: 'Arsenal', sport: 'rugby' }))
+
+    const doc = build(stadium)
+    assert.deepEqual((doc.data as any).relationships.team.data, { type: 'rugby-teams', id: '5' })
+  })
+})
+
+test.group('STI documents: unloaded belongsTo to the base', () => {
+  test('emits no data member, because the concrete type is unknowable', ({ assert }) => {
+    const stadium = make(Stadium, { name: 'Emirates', teamId: 5 })
+
+    const doc = build(stadium)
+    // With links disabled the member has nothing left and is omitted
+    // entirely; either way, no base-typed data escapes.
+    assert.isUndefined((doc.data as any).relationships?.team?.data)
+  })
+
+  test('a relationship self link survives without the data member', ({ assert }) => {
+    const stadium = make(Stadium, { name: 'Emirates', teamId: 5 })
+    const links = new LinkBuilder(true, stubRouter(), 'api.stadiums.show')
+
+    const doc = new DocumentBuilder(registry(), parseQueryParams({}), links).build(stadium)
+    const team = (doc.data as any).relationships.team
+    assert.notProperty(team, 'data')
+    assert.isDefined(team.links)
+  })
+
+  test('an unloaded belongsTo to a non-STI target keeps FK-derived linkage', ({ assert }) => {
+    class PlainStadium extends Stadium {}
+    // Stadium.team targets SportsTeam; registering it WITHOUT subtypes
+    // makes it a normal model, so the FK fallback must behave exactly as
+    // today.
+    class PlainTeamResource extends JsonApiResource<SportsTeam> {
+      static type = 'sports-teams'
+      static model = () => SportsTeam
+    }
+    const reg = new JsonApiRegistry().register([PlainTeamResource])
+    const stadium = make(PlainStadium, { name: 'Emirates', teamId: 5 })
+
+    const doc = build(stadium, {}, reg)
+    assert.deepEqual((doc.data as any).relationships.team.data, {
+      type: 'sports-teams',
+      id: '5',
+    })
+  })
+
+  test('a loaded-but-null belongsTo still says data null', ({ assert }) => {
+    const stadium = make(Stadium, { name: 'Orphan Park', teamId: null })
+    stadium.$setRelated('team', null)
+
+    const doc = build(stadium)
+    assert.isNull((doc.data as any).relationships.team.data)
+  })
+})
diff --git a/tests/unit/sti_registry.spec.ts b/tests/unit/sti_registry.spec.ts
new file mode 100644
index 0000000..2f4d9ee
--- /dev/null
+++ b/tests/unit/sti_registry.spec.ts
@@ -0,0 +1,241 @@
+/**
+ * The registry's per-row resolution seam for single-table inheritance
+ * (issue #9). A base resource declares resolveResource(row) and the
+ * registry resolves rows through it, so a SportsTeam row whose
+ * discriminator says football serializes as football-teams, not
+ * sports-teams.
+ */
+import { test } from '@japa/runner'
+import { JsonApiRegistry } from '../../src/registry.ts'
+import { JsonApiResource } from '../../src/resource.ts'
+import { FootballTeam, RugbyTeam, SportsTeam, make } from '../fixtures/models.ts'
+import {
+  FootballTeamResource,
+  RugbyTeamResource,
+  SportsTeamResource,
+  stiRegistry as registry,
+} from '../fixtures/sti_resources.ts'
+
+test.group('registry: resolveResource', () => {
+  test('a base-hydrated row resolves to its concrete resource', ({ assert }) => {
+    const row = make(SportsTeam, { name: 'Arsenal', sport: 'football' })
+    assert.strictEqual(registry().resourceForRow(row), FootballTeamResource)
+  })
+
+  test('the discriminator decides, not the constructor', ({ assert }) => {
+    const football = make(SportsTeam, { name: 'Arsenal', sport: 'football' })
+    const rugby = make(SportsTeam, { name: 'Saracens', sport: 'rugby' })
+    const reg = registry()
+    assert.strictEqual(reg.resourceForRow(football), FootballTeamResource)
+    assert.strictEqual(reg.resourceForRow(rugby), RugbyTeamResource)
+  })
+
+  test('typeForRow gives the concrete type for a base-hydrated row', ({ assert }) => {
+    const reg = registry()
+    assert.equal(reg.typeForRow(make(SportsTeam, { sport: 'football' })), 'football-teams')
+    assert.equal(reg.typeForRow(make(SportsTeam, { sport: 'rugby' })), 'rugby-teams')
+  })
+
+  test('an unrecognised discriminator falls back to the base resource', ({ assert }) => {
+    const row = make(SportsTeam, { name: 'Mystery XI', sport: 'handball' })
+    const reg = registry()
+    assert.strictEqual(reg.resourceForRow(row), SportsTeamResource)
+    assert.equal(reg.typeForRow(row), 'sports-teams')
+  })
+
+  test('models without resolveResource behave exactly as before', ({ assert }) => {
+    class PlainResource extends JsonApiResource<FootballTeam> {
+      static type = 'plain-teams'
+      static model = () => FootballTeam
+    }
+    const reg = new JsonApiRegistry().register([PlainResource])
+    const row = make(FootballTeam, { name: 'Arsenal', sport: 'football' })
+    assert.strictEqual(reg.resourceForRow(row), PlainResource)
+    assert.equal(reg.typeForRow(row), 'plain-teams')
+  })
+
+  test('typeForRow equals typeFor for unregistered models', ({ assert }) => {
+    const reg = new JsonApiRegistry()
+    const row = make(FootballTeam, { name: 'Arsenal', sport: 'football' })
+    assert.equal(reg.typeForRow(row), reg.typeFor(FootballTeam))
+  })
+
+  test('a hook returning its own class does not loop', ({ assert }) => {
+    class SelfResource extends JsonApiResource<SportsTeam> {
+      static type = 'selfies'
+      static model = () => SportsTeam
+      static resolveResource(_row: SportsTeam) {
+        return SelfResource
+      }
+    }
+    const reg = new JsonApiRegistry().register([SelfResource])
+    const row = make(SportsTeam, { sport: 'football' })
+    assert.strictEqual(reg.resourceForRow(row), SelfResource)
+    assert.equal(reg.typeForRow(row), 'selfies')
+  })
+
+  test('a chain of hooks resolves through every link', ({ assert }) => {
+    class FinalResource extends JsonApiResource<SportsTeam> {
+      static type = 'finals'
+      static model = () => SportsTeam
+    }
+    class MiddleResource extends JsonApiResource<SportsTeam> {
+      static model = () => SportsTeam
+      static resolveResource(_row: SportsTeam) {
+        return FinalResource
+      }
+    }
+    class EntryResource extends JsonApiResource<SportsTeam> {
+      static model = () => SportsTeam
+      static resolveResource(_row: SportsTeam) {
+        return MiddleResource
+      }
+    }
+    const reg = new JsonApiRegistry().register([EntryResource])
+    const row = make(SportsTeam, { sport: 'football' })
+    assert.strictEqual(reg.resourceForRow(row), FinalResource)
+    assert.equal(reg.typeForRow(row), 'finals')
+  })
+
+  test('a cycle between two hooks stops instead of looping', ({ assert }) => {
+    class AResource extends JsonApiResource<SportsTeam> {
+      static type = 'a-things'
+      static model = () => SportsTeam
+      static resolveResource(_row: SportsTeam): typeof JsonApiResource<SportsTeam> {
+        return BResource
+      }
+    }
+    class BResource extends JsonApiResource<SportsTeam> {
+      static type = 'b-things'
+      static model = () => SportsTeam
+      static resolveResource(_row: SportsTeam) {
+        return AResource
+      }
+    }
+    const reg = new JsonApiRegistry().register([AResource])
+    const row = make(SportsTeam, { sport: 'football' })
+    // resolution must terminate; landing on either class is acceptable
+    const resolved = reg.resourceForRow(row)
+    assert.include([AResource, BResource], resolved)
+  })
+})
+
+test.group('registry: subtypes register with their base', () => {
+  test('registering the base registers every declared subtype', ({ assert }) => {
+    const reg = new JsonApiRegistry().register([SportsTeamResource])
+
+    assert.equal(reg.typeFor(FootballTeam), 'football-teams')
+    assert.equal(reg.typeFor(RugbyTeam), 'rugby-teams')
+    assert.strictEqual(reg.resourceFor(FootballTeam), FootballTeamResource)
+  })
+
+  test('an explicitly registered subtype is not overwritten', ({ assert }) => {
+    class CustomFootballResource extends JsonApiResource<FootballTeam> {
+      static type = 'custom-football-teams'
+      static model = () => FootballTeam
+    }
+    const reg = new JsonApiRegistry().register([CustomFootballResource, SportsTeamResource])
+
+    assert.strictEqual(reg.resourceFor(FootballTeam), CustomFootballResource)
+  })
+})
+
+test.group('registry: typeName as the single home for type derivation', () => {
+  test('a resource overriding typeName controls its type everywhere', ({ assert }) => {
+    class VersionedTeamResource extends JsonApiResource<FootballTeam> {
+      static model = () => FootballTeam
+      static typeName() {
+        return 'v2-football-teams'
+      }
+    }
+    class RoutingResource extends JsonApiResource<SportsTeam> {
+      static model = () => SportsTeam
+      static resolveResource(_row: SportsTeam) {
+        return VersionedTeamResource
+      }
+    }
+    const reg = new JsonApiRegistry().register([RoutingResource, VersionedTeamResource])
+
+    assert.equal(reg.typeForRow(make(SportsTeam, { sport: 'football' })), 'v2-football-teams')
+    assert.equal(reg.typeFor(FootballTeam), 'v2-football-teams')
+  })
+
+  test('the default typeName is the static type, then the kebab-cased table', ({ assert }) => {
+    class NamedResource extends JsonApiResource<SportsTeam> {
+      static type = 'named-things'
+      static model = () => SportsTeam
+    }
+    class UnnamedResource extends JsonApiResource<SportsTeam> {
+      static model = () => SportsTeam
+    }
+    assert.equal(NamedResource.typeName(), 'named-things')
+    assert.equal(UnnamedResource.typeName(), 'sports-teams')
+  })
+})
+
+test.group('registry: families discovered at runtime', () => {
+  /**
+   * A family whose discriminator values are user data, so the concrete
+   * resources are built on demand. One class per value, memoized: the
+   * registry caches types per class object, and the resolution walk ends
+   * on a repeated class, so identity matters.
+   */
+  function dynamicFamily() {
+    const cache = new Map<string, typeof JsonApiResource<SportsTeam>>()
+
+    class TeamResource extends JsonApiResource<SportsTeam> {
+      static model = () => SportsTeam
+      static subtypes = () => [...cache.values()]
+      static resolveResource(row: SportsTeam) {
+        let resource = cache.get(row.sport)
+        if (!resource) {
+          resource = class extends TeamResource {
+            static type = `${row.sport}-teams`
+          }
+          cache.set(row.sport, resource)
+        }
+        return resource
+      }
+    }
+    return { TeamResource, cache }
+  }
+
+  test('rows resolve to memoized runtime-built resources', ({ assert }) => {
+    const { TeamResource } = dynamicFamily()
+    const reg = new JsonApiRegistry().register([TeamResource])
+
+    assert.equal(reg.typeForRow(make(SportsTeam, { sport: 'quidditch' })), 'quidditch-teams')
+    assert.equal(reg.typeForRow(make(SportsTeam, { sport: 'chess' })), 'chess-teams')
+    // the same value resolves to the same class, not a fresh one
+    assert.strictEqual(
+      reg.resourceForRow(make(SportsTeam, { sport: 'quidditch' })),
+      reg.resourceForRow(make(SportsTeam, { sport: 'quidditch' }))
+    )
+  })
+
+  test('a kind discovered after boot is accepted on writes', ({ assert }) => {
+    const { TeamResource } = dynamicFamily()
+    const reg = new JsonApiRegistry().register([TeamResource])
+
+    // boot time: no kinds exist yet, so no types are accepted
+    assert.deepEqual(reg.acceptedTypesFor(SportsTeam), [])
+
+    // a row with a new kind arrives and resolves
+    reg.typeForRow(make(SportsTeam, { sport: 'quidditch' }))
+
+    // subtypes() is consulted per write, so the family grew
+    assert.deepEqual(reg.acceptedTypesFor(SportsTeam), ['quidditch-teams'])
+  })
+
+  test('a runtime-built resource serializes through the inherited chain safely', ({ assert }) => {
+    // the dynamic class inherits resolveResource from its base; resolving
+    // again returns the same memoized class, which ends the walk
+    const { TeamResource } = dynamicFamily()
+    const reg = new JsonApiRegistry().register([TeamResource])
+    const row = make(SportsTeam, { sport: 'quidditch' })
+
+    const resolved = reg.resourceForRow(row)
+    assert.equal(reg.typeForRow(row), 'quidditch-teams')
+    assert.strictEqual(reg.resourceForRow(row), resolved)
+  })
+})
diff --git a/tests/unit/sti_writes.spec.ts b/tests/unit/sti_writes.spec.ts
new file mode 100644
index 0000000..0ffd22c
--- /dev/null
+++ b/tests/unit/sti_writes.spec.ts
@@ -0,0 +1,245 @@
+/**
+ * Write paths accept the STI family (issue #9). A relation targeting a
+ * base resource that declares subtypes accepts any member type in the
+ * family, and rejects types outside it, including the base's own
+ * abstract type, which never belongs in a payload. Rejections happen
+ * before any database access, so they are unit-testable; the accept-and-
+ * attach paths are covered functionally in the example app.
+ */
+import { test } from '@japa/runner'
+import { JsonApiRegistry } from '../../src/registry.ts'
+import { JsonApiResource } from '../../src/resource.ts'
+import { JsonApiException } from '../../src/errors.ts'
+import { deserializeResourceDocument } from '../../src/deserializer.ts'
+import { updateRelationship } from '../../src/relationships.ts'
+import { Fan, SportsTeam, Stadium, make } from '../fixtures/models.ts'
+import { stiRegistry as registry } from '../fixtures/sti_resources.ts'
+
+async function rejection(fn: () => Promise<unknown>): Promise<JsonApiException> {
+  try {
+    await fn()
+  } catch (error) {
+    return error as JsonApiException
+  }
+  throw new Error('expected the call to reject, it resolved')
+}
+
+test.group('STI writes: resource body (deserializer)', () => {
+  test('a belongsTo to the base accepts any family member type', ({ assert }) => {
+    for (const type of ['football-teams', 'rugby-teams']) {
+      const result = deserializeResourceDocument(Stadium, registry(), {
+        data: {
+          type: 'stadiums',
+          attributes: { name: 'Emirates' },
+          relationships: { team: { data: { type, id: '5' } } },
+        },
+      })
+      assert.equal(result.attributes.teamId, '5')
+    }
+  })
+
+  test('a type outside the family is a 409 naming every acceptable type', ({ assert }) => {
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(Stadium, registry(), {
+          data: {
+            type: 'stadiums',
+            relationships: { team: { data: { type: 'trains', id: '5' } } },
+          },
+        }),
+      JsonApiException
+    ) as unknown as JsonApiException
+
+    assert.equal(error.status, 409)
+    assert.match(error.errors[0].detail!, /football-teams/)
+    assert.match(error.errors[0].detail!, /rugby-teams/)
+  })
+
+  test('the abstract base type is rejected too', ({ assert }) => {
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(Stadium, registry(), {
+          data: {
+            type: 'stadiums',
+            relationships: { team: { data: { type: 'sports-teams', id: '5' } } },
+          },
+        }),
+      JsonApiException
+    ) as unknown as JsonApiException
+    assert.equal(error.status, 409)
+  })
+
+  test('a to-many to the base accepts mixed family types in one payload', ({ assert }) => {
+    const result = deserializeResourceDocument(Fan, registry(), {
+      data: {
+        type: 'fans',
+        attributes: { name: 'Liam' },
+        relationships: {
+          favourites: {
+            data: [
+              { type: 'football-teams', id: '1' },
+              { type: 'rugby-teams', id: '2' },
+            ],
+          },
+        },
+      },
+    })
+    assert.deepEqual(result.toMany.favourites, ['1', '2'])
+  })
+
+  test('a relation to a non-STI target still holds its single type', ({ assert }) => {
+    class PlainTeamResource extends JsonApiResource<SportsTeam> {
+      static type = 'sports-teams'
+      static model = () => SportsTeam
+    }
+    const reg = new JsonApiRegistry().register([PlainTeamResource])
+
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(Stadium, reg, {
+          data: {
+            type: 'stadiums',
+            relationships: { team: { data: { type: 'football-teams', id: '5' } } },
+          },
+        }),
+      JsonApiException
+    ) as unknown as JsonApiException
+    assert.equal(error.status, 409)
+  })
+})
+
+test.group('STI writes: relationship endpoints (parse stage)', () => {
+  test('a to-one write with a type outside the family is a 409', async ({ assert }) => {
+    const stadium = make(Stadium, { name: 'Emirates', teamId: 7 })
+
+    const error = await rejection(() =>
+      updateRelationship(
+        stadium,
+        'team',
+        registry(),
+        { data: { type: 'trains', id: '1' } },
+        'replace'
+      )
+    )
+    assert.equal(error.status, 409)
+    assert.match(error.errors[0].detail!, /football-teams/)
+  })
+
+  test('a to-many write with a type outside the family is a 409', async ({ assert }) => {
+    const fan = make(Fan, { name: 'Liam' })
+
+    const error = await rejection(() =>
+      updateRelationship(
+        fan,
+        'favourites',
+        registry(),
+        { data: [{ type: 'trains', id: '1' }] },
+        'add'
+      )
+    )
+    assert.equal(error.status, 409)
+    assert.match(error.errors[0].detail!, /rugby-teams/)
+  })
+
+  test('the abstract base type is rejected at the endpoint too', async ({ assert }) => {
+    const fan = make(Fan, { name: 'Liam' })
+
+    const error = await rejection(() =>
+      updateRelationship(
+        fan,
+        'favourites',
+        registry(),
+        { data: [{ type: 'sports-teams', id: '1' }] },
+        'add'
+      )
+    )
+    assert.equal(error.status, 409)
+  })
+})
+
+test.group('STI writes: primary data', () => {
+  /**
+   * A wildcard endpoint (/api/v1/:type) deserializes against the base
+   * model, so the primary data.type check has to accept the family, not
+   * one string. The matched type comes back on the result so the
+   * controller can stamp the discriminator and compare against the URL.
+   */
+  test('a family member type is accepted against the base model', ({ assert }) => {
+    const result = deserializeResourceDocument(SportsTeam, registry(), {
+      data: {
+        type: 'football-teams',
+        attributes: { name: 'Arsenal' },
+      },
+    })
+    assert.equal(result.type, 'football-teams')
+    assert.equal(result.attributes.name, 'Arsenal')
+  })
+
+  test('the abstract base type is rejected as primary data', ({ assert }) => {
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(SportsTeam, registry(), {
+          data: { type: 'sports-teams', attributes: { name: 'X' } },
+        }),
+      JsonApiException
+    ) as unknown as JsonApiException
+    assert.equal(error.status, 409)
+  })
+
+  test('a type outside the family is a 409 naming every acceptable type', ({ assert }) => {
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(SportsTeam, registry(), {
+          data: { type: 'referees', attributes: { name: 'X' } },
+        }),
+      JsonApiException
+    ) as unknown as JsonApiException
+    assert.equal(error.status, 409)
+    assert.match(error.errors[0].detail!, /"football-teams"/)
+    assert.match(error.errors[0].detail!, /"rugby-teams"/)
+  })
+
+  test('expectedType pins the endpoint to one member of the family', ({ assert }) => {
+    const accepted = deserializeResourceDocument(
+      SportsTeam,
+      registry(),
+      { data: { type: 'football-teams', attributes: { name: 'Arsenal' } } },
+      { expectedType: 'football-teams' }
+    )
+    assert.equal(accepted.type, 'football-teams')
+
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(
+          SportsTeam,
+          registry(),
+          { data: { type: 'rugby-teams', attributes: { name: 'Saracens' } } },
+          { expectedType: 'football-teams' }
+        ),
+      JsonApiException
+    ) as unknown as JsonApiException
+    assert.equal(error.status, 409)
+  })
+
+  test('a non-STI model keeps its single-type check and reports its type', ({ assert }) => {
+    class StadiumResource extends JsonApiResource<Stadium> {
+      static type = 'stadiums'
+      static model = () => Stadium
+    }
+    const reg = new JsonApiRegistry().register([StadiumResource])
+
+    const result = deserializeResourceDocument(Stadium, reg, {
+      data: { type: 'stadiums', attributes: { name: 'Emirates' } },
+    })
+    assert.equal(result.type, 'stadiums')
+
+    const error = assert.throws(
+      () =>
+        deserializeResourceDocument(Stadium, reg, {
+          data: { type: 'arenas', attributes: { name: 'X' } },
+        }),
+      JsonApiException
+    ) as unknown as JsonApiException
+    assert.equal(error.status, 409)
+  })
+})