Business Rules & Validation

To guarantee that your backend runs safely and securely without crashes, API Now! performs automatic checks (linting) on your data structures and API configurations.

These checks ensure your database is compatible with PostgreSQL standards and that your endpoints are fully secured before going live.

Validation Severity Levels

Issues found during validation are categorized into three severity levels:

Error (Blocker): Critical issues that violate database or API integrity. Errors must be resolved before you can publish a domain or deploy an API.
Warning (Recommendation): Non-blocking issues. While they do not prevent deployment, they point out missing security settings, missing descriptions, or non-optimal configurations.
Info (Advice): Informational suggestions or best-practice notices (such as highlighting that a hard delete strategy cannot be undone).

Data Domain Validation Rules

The platform validates your database blueprint (entities, columns, and relationships) against strict database-level guidelines.

Entity (Table) Rules

Primary Key [Error]: Every entity must have a primary key (e.g., an ID property) to uniquely identify records. This can be defined directly or inherited from a parent entity.
Naming Conventions [Error]: Entity names must be unique within your model, contain only letters, numbers, or underscores, and start with a letter.
Property Bounds [Warning]: Entities should contain at least one property or association (unless they inherit properties from a parent entity).
Single Status Semantic [Error]: An entity can have at most one property annotated with the Status semantic module across its full inheritance hierarchy. An entity cannot define multiple status fields, nor inherit multiple conflicting status properties from parent entities. (Shadowing an inherited status property by redefining it on the child entity with the exact same name is permitted).

Property (Field) Rules

PostgreSQL Compatibility [Error]: Column names must not conflict with PostgreSQL reserved keywords (like SELECT, TABLE, or USER). They must follow snake_case naming conventions and be between 2 and 59 characters long.
Semantic Data Alignment [Error]: The data type of a property must match its Semantic module tag. For example, you cannot apply the CreatedTimestamp (date/time) tag to a property defined as an integer.
Default Value Must Match Enum Choices [Error]: When a property defines a list of predefined choices (enum) and has a literal default value configured, the default value must be one of the declared choices in that list. This prevents records from automatically being created with values that violate the property’s own allowed choices.
Scalar Status Property [Error]: A property annotated with the Status semantic module must be single-valued (scalar). Setting multiple: true on a status property is blocked because a record can only occupy one lifecycle state at a time.
Status Choices and Indexing [Error]: A Status property must be of type string, must define a non-empty list of predefined choices (enum), and must have database indexing enabled (index: true).
Mutual Exclusivity of Read-Only and Immutable [Error]: A property cannot be configured with both readOnly: true and immutable: true. These two flags represent conflicting write lifecycles (readOnly is write-never, whereas immutable is write-once).
Primary Key Write Lifecycle Defaults [Rule]: Marking a property as a Primary Key (primary: true) defaults its write lifecycle to readOnly: true (protecting database sequence IDs) unless it is explicitly configured as immutable: true (allowing client-assignable natural keys on create). See Primary Key Patterns.

Association (Relationship) Rules

Target Validity [Error]: Relationship links must point to target entities that actually exist in your data model.
Many-to-Many Semantic Required [Error]: Modeling a Many-to-Many relationship requires choosing an M:N Semantic module. Use PeerRelation as the generalized default for peer connections (e.g., pairings, prerequisites, cross-sells) or a specialized semantic (such as OrganizationMembers or Tags). Setting multiple: true without an M:N semantic creates a standard 1:N parent-child relationship.
PeerRelation Multiplicity [Error]: PeerRelation can only be applied to multi-valued (multiple: true) associations.
PeerRelation Nature Required [Error]: Associations tagged with PeerRelation must specify a valid business nature. If custom is selected, a descriptive customNature label is required.
Prerequisite Symmetry Conflict [Error]: A PeerRelation configured with nature: 'prerequisite' cannot use mutual symmetry, as dependency prerequisites are strictly directional.
Embedded Hydration Restriction [Error]: Setting schema.embedded: true is only permitted on single (1:1) associations. Multi-valued associations (1:N and M:N) must use dedicated sub-resource routes to maintain query performance and ensure proper permission evaluation.
Directional Nesting [Warning]: Relationships should be defined from parent to child (e.g., Post has many Comments) to enable clean nested sub-routing in your API.

API Model Validation Rules

The platform checks your API configurations to make sure they follow proper REST URL structures and are secure.

Security & Authentication

Authentication Mandatory [Error]: You must configure an authentication strategy (e.g., requiring logins or API keys) to protect your routes.
Username Semantic [Error]: If you select UsernamePassword authentication, your designated user entity must have a property tagged with the Username Semantic module.
RBAC Permissions [Error]: If you select Role-Based Access Control (RBAC) authorization, your user entity must contain a property tagged with the UserRole Semantic Module.
Session Secret [Error]: All active sessions require a secure encryption secret and at least one mapped session property (such as storing the User ID in the active session).
Action Access Rules [Error]: Every exposed database action must have at least one access rule (e.g., public, authenticated, or role-restricted) attached to it.
Match Email Domain Inclusion Required [Error]: A Match Email Domain access rule cannot consist exclusively of negative exclusion patterns (prefixed with !). At least one allowed inclusion domain (such as *.example.com or example.com) is required for exclusions to take effect.
Match Email Domain Exclusion Wildcards [Error]: Exclusion patterns in a Match Email Domain access rule must match exact domain names. Wildcards in negative patterns (such as !*.example.com) are rejected because exclusion checks operate strictly on exact domains and subdomains.
Match Email Domain Pattern Formatting [Error]: Domain patterns in a Match Email Domain access rule cannot be empty, cannot consist of a bare exclamation mark (!), and must not include @ symbols or web protocols (such as https://).

Routing & Path Rules

Path Integrity [Error]: Collection paths must start with a / and parameter placeholders must use curly braces (e.g., /customers/{customerId}).
Route Collisions [Error]: Root-level paths must be unique across your API Model to prevent endpoint conflicts.
Resource Parameter Formatting [Error]: Resource paths must match their parent collection paths (e.g., /products must map to /products/{productId}).

Actions Configuration

Minimum Operations [Error]: Every exposed entity must enable at least one action (e.g. permitting users to “Read” or “List”).
Pagination Mandatory [Error]: To prevent server overloads, the List action requires a pagination style to be configured (either offset or cursor).
Search Index [Error]: The Search action requires you to select at least one text property to perform the search query against.

Current User (`/me`) Endpoint Rules

User Semantic Required [Error]: A Current User (/me) endpoint can only be created for an entity tagged with the User semantic module.
Parent Collection Required [Error]: A Current User (/me) endpoint must attach to a parent exposure that has an active collection endpoint.
Parent Exposure Integrity [Error]: The referenced parent User exposure must exist in the API Model.
No Association Allowed [Error]: An explicit domain association must not be defined on a Current User (/me) endpoint.
Singleton Actions Only [Error]: Only read, update, delete, and unlink actions are permitted on a Current User (/me) endpoint. Collection actions like list, create, search, and link are forbidden.
Single Endpoint Per Parent [Error]: Only one /me child endpoint can be created per parent collection exposure.

How to Run Validation

The API Now! platform runs these checks automatically when you save drafts in the visual modelers. If you are developing locally, you can run the validation manually via the CLI:

# Validate your local data domain schema:
npx apinow validate path/to/domain.json

# Validate your local API model schema against its domain:
npx apinow validate path/to/api.json --domain path/to/domain.json