Data Associations

A Data Association (DomainAssociation) defines how database entities relate to one another (e.g., a User has many Posts, or an Order has many LineItems).

The Serverless Engine automatically translates these associations into standard foreign keys, index structures, and database constraints.

---

Designing Associations: Parent-to-Child Priority

When designing your database schema in the Domain Modeler, always prioritize defining associations from the Parent entity to the Child entity (e.g., defining User → Posts or User → Profile).

Why Parent-to-Child Matters for API Routing

While relational databases support bidirectional queries, the API Modeler relies on Parent-to-Child associations to generate nested endpoints.

• Hierarchical Routes: If you want to structure your endpoints hierarchically (e.g., /users/{userId}/posts to list posts belonging to a specific user), the Serverless Engine requires an association pointing from the parent (User) to the child (Post).
• Runtime Recognition: If you only define the inverse “belongs to” association (e.g., Post pointing back to User), the runtime will not recognize the nested relationship, and you will not be able to configure nested child routes in the API Modeler.
• Coexistence: You can define both directions if needed, but the parent-to-child direction is a strict prerequisite for nested API endpoint structure.

---

Association Parameters

When you configure an association in the Domain Modeler, you define the following options:

1. Targets

The association specifies one or more target entities it connects to. For example, a User entity has an association pointing to the target Post entity.

2. Cardinality (Multiple) & Many-to-Many (M:N) Relationships

The Multiple toggle checkbox determines the cardinality of the relationship:

• multiple: false (One-to-One / Many-to-One): The current entity holds a reference to a single target record (e.g., User has a Profile with multiple: false, mapping to a single foreign key reference).
• multiple: true without an M:N Semantic (One-to-Many / 1:N): Represents a hierarchical list of owned child records (e.g., Order has many LineItems). This uses a standard Foreign Key constraint on the child table, avoiding unnecessary join tables.
• multiple: true with an M:N Semantic (Many-to-Many / M:N): When multiple: true is tagged with an M:N semantic module, the platform automatically provisions and manages an underlying link table (join table) in the database.

---

Many-to-Many (M:N) Relationships

In traditional database modeling, developers create generic, untyped “join tables” that lack business context. In API Now, all Many-to-Many relationships are semantic-driven—they convey explicit business meaning that both developers and AI agents can reason about.

1. Two Flavors of M:N Semantics

When modeling an M:N relationship, you choose between two categories of semantic modules:

A. Generalized Default: PeerRelation

Use PeerRelation whenever you connect two independent peer records that do not own each other’s lifecycle:

• Real-World Examples: Food pairings (Menu $\leftrightarrow$ Menu), course prerequisites (Course $\rightarrow$ Course), related articles (Article $\leftrightarrow$ Article), or accessory cross-sells (Product $\rightarrow$ Product).
• Relational Natures: Choose from 8 built-in business purposes: recommendation, cross_sell, prerequisite, alternative, reference, assignment, compatibility, or custom.
• Directionality & Symmetry: Configure whether the link is one-way (directed, e.g., Course A requires Course B) or bidirectional (mutual, e.g., Wine A complements Dish B).
• Automatic Safeguards: Relationships defined as prerequisites automatically prevent circular dependencies (cycles) at runtime.

B. Specialized M:N Semantics

Use specialized modules when the relationship serves a specific platform or domain role:

• OrganizationMembers: Binds users to organizations with tenant access scoping and membership roles.
• ProjectMembers: Binds users to project collaboration workspaces.
• Tags & Categories: Manages taxonomy classifications and multi-tag indexing.

---

2. Self-Referencing Relationships

Entities can connect to records of the exact same entity type (e.g., a Menu item paired with another Menu item, or a Course requiring another Course).

You simply create an association on the entity where the target is the entity itself, and tag it with PeerRelation. The platform automatically employs heuristics to manage the underlying link table and prevent naming collisions, ensuring clean and reliable queries without manual database configuration.

---

3. Relationship Attributes (Edge Properties)

Real-world relationships often have their own contextual attributes:

• A food pairing has an affinity score and chef notes.
• An organization membership has a member role and joined date.
• An operational assignment has an assigned date and status.

In API Now, you do not need to create an intermediate entity just to store relationship fields. You can add properties directly to the reference in the Data Modeler:

• For specialized semantics like OrganizationMembers, standard edge properties (like role) are provisioned automatically.
• For PeerRelation, you can click the Add property button directly on the semantic item in the reference details panel. The new field appears under the reference in the entity editor, where you can open the property editor to configure its name, scalar type, and attributes.

Edge Property Write Lifecycle

Relationship edge properties also support standard Write Lifecycle configurations:

• immutable: true (Write-Once): For attributes established at the inception of a relationship (such as joined_at, invited_by, or source_referral). Callers can supply a value when linking records (POST /{collection}/{id}/{subResource}), but the value cannot be modified during subsequent edge updates (PUT).
• readOnly: true (System-Managed): For metrics or timestamps calculated and managed automatically by the runtime.
• Primary Key Restriction: Edge properties cannot be marked as primary: true; composite identity on junction tables is governed by the foreign keys of the connected entities.

---

4. Dual-Sided Modeling & Single Link Table

If you want to access a Many-to-Many relationship from both directions in your API (e.g., viewing a user’s organizations and an organization’s users, or viewing a doctor’s patients and a patient’s doctors):

1. Create the association from Entity A to Entity B and tag it with the M:N semantic.
2. Create the reciprocal association from Entity B to Entity A and tag it with the matching semantic module.

The platform automatically manages a single underlying link table in the database while allowing you to configure API endpoints on either or both sides in the API Modeler.

---

Association Semantics

Attach specialized access control, tenancy, and relationship semantics directly to associations:

• PeerRelation: Generalized default M:N semantic for peer connections with business nature, symmetry, and cycle detection.
• OrganizationMembers: M:N semantic linking an Organization to User members with role-based access control.
• ProjectMembers: M:N semantic linking a Project to User collaborators.
• ResourceOwnerIdentifier: Binds a resource directly to the logged-in system user for automatic row-level security.
• RelationalResourceOwner: Binds a sub-resource to a parent resource (e.g., a Comment pointing to its parent Post), inheriting owner permissions transitively.

---

Relational Constraints & Best Practices

• Foreign Keys & Link Tables: Single associations (multiple: false) generate standard foreign key columns. Multi-valued peer associations (multiple: true with an M:N semantic) generate optimized link tables.
• Embedded Hydration (schema.embedded) is 1:1 Only: Inlining full associated records into parent responses is supported exclusively for single (1:1) associations. Multi-valued relationships (1:N collections and M:N peer relations) use dedicated, paginated sub-resource endpoints to maintain high performance and enforce row-level security.
• Cascading Deletes: Parent-child relationships support cascading deletes to clean up owned records. In contrast, unlinking peer records in an M:N relationship removes only the connection in the link table, leaving both primary records untouched.
• Automatic Indexing: The deployment engine automatically creates database indexes on foreign keys and link tables to ensure fast query execution.