Status (Semantic Module)

← Back to Modules Reference

The Status semantic module is applied to an entity property to manage record lifecycles and state machine workflows. It turns a standard text or enum field into an active state machine that controls valid state transitions (e.g., draft → in_review → published → archived), sets default creation states, and integrates directly with API authorization.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied directly to an entity property)
Data Type	Enum / String
Default Configuration	Allowed states: ['draft', 'published', 'archived'], Default state: 'draft'
State Machine Engine	Validates transitions against configured transition graphs
Authorization Integration	Auto-detected by the Match Lifecycle Status access rule

---

Key Capabilities

1. State Machine & Allowed Transitions

The Status semantic module enforces strict state machine rules on your records. You can define exact valid next steps for each state:

stateDiagram-v2
    [*] --> draft : Default on Create
    draft --> in_review : Submit for Review
    in_review --> published : Approve
    in_review --> draft : Request Changes
    published --> archived : Archive
    archived --> [*]

• Transition Validation: If a client attempts an illegal jump (for example, moving directly from draft to archived when transitions only allow draft -> ['in_review']), the runtime rejects the request with a 422 Validation Error.

2. Default State on Creation

When a new record is created (via a POST action), the runtime automatically assigns the configured defaultState (such as draft or pending) if no status is explicitly provided in the request body.

3. State Behaviors & Operational Permissions

Each state can be customized with specific operational flags:

• isPublic: Whether records in this state are visible to unauthenticated or public callers.
• isEditable: Whether records in this state can undergo field edits.
• isDeletable: Whether records in this state can be deleted.
• requiresApproval: Whether transitioning into or out of this state requires elevated approval roles.

4. Integration with API Authorization

The Status semantic module powers the Match Lifecycle Status access rule in the API Modeler:

• The authorization engine automatically locates the property tagged with Status.
• You can define Access Scenarios using allowedStatuses (e.g., public callers only see published records) and deniedStatuses (e.g., authors cannot edit archived or settled invoices).

---

API Lifecycle Examples

In this example, an entity named Article has a property named status tagged with the Status semantic module, configured with transitions draft -> ['in_review'] and in_review -> ['published', 'draft'].

1. Creating a Record (Auto Default State)

When an author creates a new article without providing a status:

POST /articles
{
  "title": "Getting Started with API Now",
  "content": "API Now makes API development fast and visual."
}

The system automatically initializes status to draft:

{
  "id": "art_10293",
  "title": "Getting Started with API Now",
  "content": "API Now makes API development fast and visual.",
  "status": "draft",
  "created_at": "2026-08-27T16:00:00Z"
}

---

2. Invalid Transition Attempt (Blocked by Engine)

A client tries to move an article directly from draft to published:

PATCH /articles/art_10293
{
  "status": "published"
}

The engine blocks the invalid transition and returns a RFC 9457 Problem Details error:

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "code": "INVALID_STATE_TRANSITION",
  "detail": "Cannot transition status from 'draft' to 'published'. Allowed next states are: ['in_review'].",
  "instance": "/articles/art_10293"
}

---

3. Valid State Transition

The client submits the article for review (draft → in_review):

PATCH /articles/art_10293
{
  "status": "in_review"
}

{
  "id": "art_10293",
  "status": "in_review",
  "updated_at": "2026-08-27T16:05:00Z"
}

---

Validation Rules & Guidelines

• One Status per Entity: An entity should only have one property tagged with the Status semantic module to prevent conflicting lifecycle states.
• Enum Compatibility: If enum values are defined on the domain property, the Status module will automatically use those enum options as the allowed states.
• Access Rule Pairing: When restricting endpoint visibility based on status, configure the Match Lifecycle Status access rule in your API Model.