ProjectMembers (Semantic Module)

← Back to Modules Reference

The ProjectMembers semantic module is applied to associations linking a Project entity to a User entity to represent project membership and collaboration.

ProjectMembers is a Many-to-Many (M:N) semantic module that automatically manages the membership relationship, governs relationship edge attributes (e.g., project roles like owner, admin, editor, viewer and status), and enables Sub-Resource API endpoints for managing project collaborators.

---

Technical Specifications

Attribute	Specification
Scope	Association (Applied to a relationship between entities)
Relationship Type	Many-to-Many (multiple: true)
Has Configuration	Yes (via ProjectMembersConfig)

---

Design Guidelines

1. Relationship Edge Properties

When ProjectMembers is applied to a relationship, the platform automatically provisions standard relationship edge properties (such as member role and status). In the UI, you enable the edge properties required for your API and can customize options like display names or allowed role values, while core property settings and data types are managed automatically by the platform.

2. Dual-Sided Modeling & Single Link Table

To allow project membership traversal from both directions:

• Define an association on Project pointing to User tagged with ProjectMembers.
• Define a reciprocal association on User pointing to Project tagged with the exact same ProjectMembers module.

The runtime manages a single underlying link table while allowing the API Modeler to expose Sub-Resource endpoints from either or both directions (such as /projects/{projectId}/users and /users/{userId}/projects).

---

Configuring in the Domain Modeler

1. Open the Domain Modeler and select your Project entity.
2. Add an association pointing to the User entity (e.g. named members or collaborators).
3. Check the Multiple checkbox (multiple: true).
4. In the association details panel, select ProjectMembers under Semantic Modules.
5. (Optional) Enable relationship edge properties (such as role or status) and customize allowed values in the UI.

---

CRUD on Sub-Resource Endpoints

In the API Modeler, associations tagged with ProjectMembers are exposed as configurable Sub-Resources under parent entities.

Operations from the Project Side (/projects/{projectId}/users)

• List Members (GET): GET /projects/proj_123/users returns an array of member users with embedded edge properties (role, status).
• Link Member (POST): POST /projects/proj_123/users with payload { "id": "user_456", "role": "editor" } adds a user to the project.
• Read Member Edge (GET): GET /projects/proj_123/users/user_456 views member details and edge attributes.
• Update Edge Attributes (PATCH): PATCH /projects/proj_123/users/user_456 with payload { "role": "admin" } modifies the member’s project role on the link table.
• Unlink Member (DELETE): DELETE /projects/proj_123/users/user_456 removes the user from the project without deleting the user or project record.

---

Independent Entity Lifecycles

M:N Sub-Resource operations enforce strict Independent Entity Lifecycles:

• Pre-existing Entities Required: Both Project and User entities must exist in the database before invoking a POST link operation.
• No Nested Creation: Users must be created via /users before being linked to a project.
• No Cascading Deletion: Removing a project member removes only the link record.