Match Relational Resource Owner

The Match Relational Resource Owner (relationalResourceOwner) access rule enforces URL-anchored inherited ownership. It grants access to a nested child resource when the authenticated user owns a qualifying parent or ancestor resource present in the route URL path.

---

1. How It Works

In many applications, child records do not maintain a direct foreign key to the User table. Instead, they belong to a parent container (such as a Document, Invoice, or Article) that is directly owned by a user:

GET /api/v1/documents/:documentId/attachments/:attachmentId

• The Attachment record does not store a user_id.
• The engine resolves the parent :documentId parameter from the URL path.
• It verifies whether the authenticated user owns the parent Document.
• If the user owns the parent document, access to the child Attachment is granted.

Property	Specification
Rule Type	relationalResourceOwner
Supported Strategies	All strategies (RBAC, OrganizationRBAC, EnterpriseRBAC)
Allowed Placement Levels	Exposed Entity Level (exposure), Action Level (action) (Not allowed at global API Model Level)
Execution Phases	PRE_FETCH (create, read, update, delete, link, unlink), FETCH (list, search)

---

2. Direct vs. Relational Ownership

Feature	Match Resource Owner (matchResourceOwner)	Match Relational Resource Owner (relationalResourceOwner)
Ownership Link	Direct: The resource has a direct FK to User (or IS the User).	Indirect: Ownership is inherited from a parent in the URL route.
URL Hierarchy	Works on flat routes (/documents/:id).	Requires a nested parent route parameter (e.g. /documents/:documentId/attachments).
create Action Support	❌ Not supported (record does not exist yet).	✅ Supported (parent already exists in the URL path).
Configuration	Handled on direct entities.	Zero Configuration (automatically resolves parent from URL).

---

3. How Parent Resolution Works

The engine automatically inspects the route path from right to left (nearest parent ancestor first) to identify the qualifying parent entity:

/api/v1/organizations/{orgId}/documents/{documentId}/attachments/{attachmentId}
         ↑ Candidate                  ↑ Nearest Parent (Wins)

A parent segment qualifies if it represents a resource with a URL parameter and matches one of two cases:

Case A: Parent Has a ResourceOwnerIdentifier Association

The parent entity (e.g. Document) has a foreign key to User tagged with ResourceOwnerIdentifier.

• Runtime Check: The engine executes a single targeted query:

  SELECT id FROM documents WHERE id = :documentId AND owner_id = :current_user_id

Case B: Parent IS the User Entity

The parent segment in the URL represents the User entity itself (e.g. /users/:userId/posts/:postId).

• Runtime Check: The engine checks in-memory String(params.userId) === String(currentUser.id) without database overhead.

---

4. Why create Actions Are Supported

Unlike direct ownership rules, Match Relational Resource Owner can protect create (POST) actions.

When creating a child record (e.g. POST /documents/:documentId/attachments):

1. The parent Document already exists in the database.
2. The engine checks that the authenticated user owns :documentId in the PRE_FETCH phase.
3. If the user owns the parent document, creation of the child record proceeds safely.

---

5. Prerequisites in the Data Domain

To use Match Relational Resource Owner:

1. Parent Ownership Annotation:
   • The parent entity must either be annotated with the User semantic module, OR have an association to User tagged with ResourceOwnerIdentifier.
2. Child Association Annotation:
   • The incoming relationship from the parent to the child entity should be annotated with RelationalResourceOwner.
3. Nested Route Design:
   • The child endpoint must be exposed under a nested URL path containing the parent parameter (e.g. /documents/:documentId/attachments).

---

6. Recommended Modeling Patterns

Pattern 1: Nested Child Resources (/documents/:documentId/attachments)

Protect child items that belong to a user-owned parent document:

graph LR
    subgraph "Nested Route Hierarchy"
        User["Authenticated User"] -->|Direct Owner| Doc["Document (:documentId)"]
        Doc -->|Inherited Ownership| Att["Attachment (:attachmentId)"]
    end

• On Attachment entity actions (list, read, create, update, delete):
  • Scenario: [Allow Authenticated, Match Relational Resource Owner]
• Any user who owns :documentId has full management rights over its nested attachments.

---

Pattern 2: Staff Override + Nested Relational Owner

Allow platform staff to moderate nested items while restricting standard users to their own parent resources:

Attachment.delete Scenarios:
├── Scenario 1 (Platform Staff Override):
│   └── Match User Role: ['admin', 'moderator']       <- Staff can delete attachments in any document
└── Scenario 2 (Document Owner):
    ├── Allow Authenticated
    └── Match Relational Resource Owner                <- Caller must own parent :documentId

---

7. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint requires Match Relational Resource Owner	401 Unauthorized
Caller Owns Parent Resource	User is the verified owner of the parent in :parentId	200 OK / 201 Created / 204 No Content
Caller Does NOT Own Parent	User is logged in, but does not own :parentId	403 Forbidden
Parent Resource Not Found	:parentId does not exist in the database	404 Not Found

---

Next Steps

• Match Resource Owner: Direct ownership checks for entities with their own User foreign key.
• Relational Resource Owner Semantic: Complete data modeling reference for relational ownership associations.
• Resource Owner Identifier Semantic: Tagging direct ownership foreign keys in the Data Modeler.