RelationalResourceOwner (Semantic Module)

The RelationalResourceOwner semantic module is used to represent transitive, relationship-based ownership.

In many applications, sub-records (like an InvoiceLineItem or a Comment) do not link directly to a User. Instead, they belong to a parent entity (like an Invoice or a Post), which is owned by a user. By applying the RelationalResourceOwner tag to the parent relationship on a sub-record, the platform automatically inherits the security permissions and access rules of that parent record.

Technical Specifications

Attribute	Specification
Scope	`Association` (Applied to relationships between parent and child entities)
Data Type	Association / Foreign Key
Write Behavior	Checked transitively at runtime to ensure the user owns the parent record

How It Works Automatically

1. Transitive Ownership Resolution

When a user attempts to read, write, update, or delete a sub-record, the Serverless Engine follows the relationship marked with RelationalResourceOwner to the parent entity. It then checks the parent entity’s owner. If that parent entity also inherits ownership, the system continues up the chain until it finds the terminal user relationship marked with the ResourceOwnerIdentifier semantic.

2. Guarding Child Records

If a user tries to create or modify a child record (e.g. adding a line item to an invoice):

The system checks the parent invoice.
If the logged-in user does not own the parent invoice, the request is immediately rejected. This prevents users from sneaking records into databases under other users’ parent accounts.

3. Inherited Filtering & Interception

When an endpoint exposing child records is protected by MatchResourceOwnerAccessRule, the runtime automatically joins the query with parent tables to verify that the ultimate owner matches the authenticated user.

Listings of child records are automatically filtered.
Unauthorized access to a single child record is blocked and returns a 404 Not Found (to protect against ID harvesting).

Example Scenario

Consider a multi-tenant Food Truck delivery platform:

A Company is owned by a User (relationship marked as ResourceOwnerIdentifier).
A Truck belongs to a Company (relationship marked as RelationalResourceOwner).
An InventoryItem belongs to a Truck (relationship marked as RelationalResourceOwner).

When checking if a user has access to edit an InventoryItem, the system automatically resolves the following chain:

graph LR
    Item[InventoryItem] -- RelationalResourceOwner --> Truck[Truck]
    Truck -- RelationalResourceOwner --> Company[Company]
    Company -- ResourceOwnerIdentifier --> User[User]

Because of this chain, the user automatically owns the inventory items of all trucks belonging to their company.

Validation Rules & Errors

The Domain Modeler automatically analyzes your relationships during design to prevent orphan data or broken security chains:

Alignment Error: You must apply this semantic module to an Association relationship. Applying it to standard columns (like text or number properties) will cause a validation error.
Invalid Ownership Path Error: The platform’s linter validates that any chain of RelationalResourceOwner associations must eventually terminate at a user entity via a ResourceOwnerIdentifier association. If a child record points to a parent that has no path to a user, the linter will flag a relational_owner_path_valid error:
```
The target entity "Truck" of the relational resource owner association "company" does not have a valid ownership path to a User. Ensure the target entity has a direct owner (Resource Owner Identifier) or transitively inherits ownership through another relational owner association.
```

ResourceOwnerIdentifier: Sets the direct owner of a database entity, anchoring the security chain.