OrganizationMembers (Semantic Module)

← Back to Modules Reference

The OrganizationMembers semantic module is applied to associations linking the Organization entity to the User entity to represent organization membership.

OrganizationMembers is a Many-to-Many (M:N) semantic module. It automatically manages the membership relationship, governs relationship edge attributes (e.g., member roles), and enables Sub-Resource API endpoints for managing team members.

---

Technical Specifications

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

---

Design Guidelines

1. Relationship Edge Properties

When OrganizationMembers is applied to a relationship, the platform automatically provisions standard relationship edge properties (such as role tagged with OrganizationRole 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 membership traversal from both directions:

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

The runtime manages a single underlying link table while allowing the API Modeler to expose Sub-Resource endpoints from either or both directions.

---

Configuring in the Domain Modeler

1. Open the Domain Modeler and select your Organization entity.
2. Add an association pointing to the User entity (e.g. named users or members).
3. Check the Multiple checkbox (multiple: true).
4. In the association details panel, select OrganizationMembers under Semantic Modules.
5. (Optional) Add edge properties directly to the association (e.g., adding a role property tagged with OrganizationRole).

---

CRUD on Sub-Resource Endpoints

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

Operations from the Organization Side (/organizations/{orgId}/users)

1. List Members (GET /organizations/{orgId}/users)

Returns an array of User objects, embedding the pivot table edge properties inside each item response:

[
  {
    "id": "user123",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "admin"
  }
]

2. Link Member (POST /organizations/{orgId}/users)

Inserts a record into the pivot table linking the organization and the user:

// POST /organizations/org_999/users
{
  "id": "user123",
  "role": "admin"
}

(Note: id references the primary key of the target User entity).

3. Read Member Edge (GET /organizations/{orgId}/users/{userId})

Returns the specific User object along with its edge properties for this organization.

4. Update Edge Attributes (PATCH /organizations/{orgId}/users/{userId})

Modifies properties stored on the pivot table edge (e.g., changing the user’s role):

// PATCH /organizations/org_999/users/user123
{
  "role": "owner"
}

(Note: Modifies only the join table record. Requests attempting to alter global User properties are rejected).

5. Unlink Member (DELETE /organizations/{orgId}/users/{userId})

Removes the record from the pivot table, breaking the membership link without deleting the User or Organization entities.

Operations from the User Side (/users/{userId}/organizations)

If reciprocal associations are configured and exposed, the exact same pivot data can be managed from the reverse direction:

• GET /users/{userId}/organizations: [{ "id": "org999", "name": "Acme Corp", "role": "admin" }]
• POST /users/{userId}/organizations: { "id": "org999", "role": "admin" }

---

Independent Entity Lifecycles

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

• Pre-existing Entities Required: Both the Organization and User entities must exist in the database before calling the POST link endpoint.
• No Nested Creation: The M:N endpoint does not accept full User object payloads to create new users on the fly. Users must be created via /users first.
• No Cascading Deletion: Deleting a membership link via DELETE /organizations/{orgId}/users/{userId} destroys only the pivot table record.