Data Organization (Namespaces & Data Models)

In complex applications, a single flat database schema can quickly become disorganized and difficult to maintain. API Now! provides a hierarchical organization system based on Data Namespaces and Data Models to keep your database blueprints structured, clear, and reusable.

---

The Data Domain Hierarchy

At the core, your database design is encapsulated in a Data Domain (the root container). Within a Data Domain, you organize your elements using the following logical structure:

DataDomain (Root container)
  ├── DomainNamespace (logical grouping)
  │   ├── DomainModel (database schema segment)
  │   │   └── DomainEntity (database table)
  │   └── ChildNamespace
  └── DomainModel
      └── DomainEntity

---

Data Namespaces

A Data Namespace (DomainNamespace) is a logical folder or group used to categorize related data structures.

Key Characteristics

• Hierarchical: Namespaces can be nested inside other namespaces to build a multi-level folder structure.
• Single Parent: Each namespace belongs to exactly one parent container (either another namespace or the root Data Domain).
• Logical Only: Namespaces are used strictly for organization within the Domain Modeler workspace; they do not create physical boundaries in the generated SQL database.

When to use

• Grouping schemas by department (e.g., Finance, Operations, HR).
• Grouping schemas by module (e.g., Billing, Identity, Support).

---

Data Models

A Data Model (DomainModel) is the container that holds your actual database tables (Data Entities).

Key Characteristics

• Table Container: You cannot create database tables directly inside a namespace; they must reside inside a Data Model.
• Physical Boundary: A Data Model represents a functional module or schema segment (e.g., Blog or CustomerProfiles).
• Parent Container: A Data Model can live directly under the root Data Domain, or be placed inside a parent Data Namespace. Each Data Model can have only one parent.

---

Best Practices for Organization

1. Keep it Shallow: Avoid nesting namespaces more than 2 or 3 levels deep to keep paths readable.
2. Modular Data Models: Create distinct Data Models for distinct business concerns (e.g., a Billing model for payments and a Catalog model for products) instead of putting all tables into a single giant model.
3. Namespace for Visibility: Use top-level namespaces to separate core system tables (like users and sessions) from domain-specific business features.