aws-amplify / aws-amplify/amplify-data
Add `allow.throughRelation()` to the schema builder API
- Dominant language
- TypeScript
- Stars
- 18
- Forks
- 23
- Avg merge
- 26m
- Merged PRs (30d)
- 1
Description
### Package version
`@aws-amplify/data-schema@1.x` (latest)
### Describe the feature
This is the `data-schema` companion to [aws-amplify/amplify-category-api#3447](https://github.com/aws-amplify/amplify-category-api/issues/3447), which proposes a `throughRelation` authorization strategy where child models inherit permissions from a parent model via a `belongsTo` relationship — eliminating the need to duplicate owner/editor/viewer arrays on every child record.
The `data-schema` package needs a new `allow.throughRelation()` builder method:
```typescript
Document: a.model({
name: a.string().required(),
blocks: a.hasMany("DocumentBlock", "documentId"),
editors: a.string().array(),
viewers: a.string().array(),
})
.authorization((allow) => [
allow.owner(),
allow.ownersDefinedIn("editors").to(["read", "update", "create", "delete"]),
allow.ownersDefinedIn("viewers").to(["read"]),
]),
DocumentBlock: a.model({
content: a.string(),
documentId: a.id().required(),
document: a.belongsTo("Document", "documentId"),
})
.authorization((allow) => [
allow.throughRelation("document"), // inherits Document's auth rules
]),
```
Two changes needed:
1. **`Authorization.ts`** — Add `throughRelation(relationField: string)` to the `allow` object, storing `{ strategy: "throughRelation", relationField }` in `[__data]`
2. **`SchemaProcessor.ts`** — In `calculateAuth()`, emit `@auth(rules: [{ allow: throughRelation, throughRelation: "document" }])` in the SDL output so the auth transformer in `amplify-category-api` can consume it
This is additive — no existing builder methods or types change.
### Use case
In collaborative applications (document editors, project management tools, shared notebooks), authorization is defined on a parent record and child records should inherit those permissions. Today, every child model must duplicate `ownersDefinedIn` arrays and keep them in sync via a Lambda cascade — which is fragile, expensive, and creates race conditions.
With `throughRelation`, permissions are defined once on the parent model. Child models reference the parent via a `belongsTo` field and the generated AppSync resolvers check the parent's permission fields at runtime. Adding a new role to the parent (e.g., `allow.ownersDefinedIn("commenters").to(["read", "create"])`) automatically applies to all child models on the next deploy — zero changes to child models.
See [aws-amplify/amplify-category-api#3447](https://github.com/aws-amplify/amplify-category-api/issues/3447) for the full proposal including all 7 use cases, resolver behavior, alternatives considered, and implementation details.
Contributor guide
Research direction
Start in Authorization.ts to trace how allow builder methods store strategy data, then inspect SchemaProcessor.ts and calculateAuth() for SDL generation. The work is complete when allow.throughRelation("document") stores the relation field and produces the specified throughRelation @auth rule for the schema output; check the related amplify-category-api proposal for integration context.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100